EventStudyAPI.m

classdef EventStudyAPI < handle
    %EVENTSTUDYAPI Client for the eventstudytools.com research API.
    %
    %   api = EventStudyAPI('YOUR_API_KEY');
    %   files = struct('request_file', '01_RequestFile.csv', ...
    %                  'firm_data',    '02_FirmData.csv', ...
    %                  'market_data',  '03_MarketData.csv');
    %   results = api.run(EventStudyAPI.arcParams(), files, 'results');
    %
    %   Requires MATLAB R2016b or newer (matlab.net.http).
    %   API keys: https://www.eventstudytools.com/api-key

    properties
        ApiKey  (1,:) char
        BaseUrl (1,:) char = 'http://api.eventstudytools.com'
        Token   (1,:) char = ''
        ResultFiles struct = struct([])
    end

    properties (Constant, Hidden)
        UserAgent = 'eventstudytools-matlab/0.1.0'
    end

    methods
        function obj = EventStudyAPI(apiKey, baseUrl)
            if nargin < 1 || isempty(apiKey)
                apiKey = getenv('EST_API_KEY');
            end
            if isempty(apiKey)
                error('EventStudyAPI:noKey', ...
                    ['No API key. Pass one or set EST_API_KEY. ' ...
                     'Keys: https://www.eventstudytools.com/api-key']);
            end
            obj.ApiKey = char(apiKey);
            if nargin >= 2 && ~isempty(baseUrl)
                obj.BaseUrl = char(baseUrl);
            end
        end

        function v = getApiVersion(obj)
            %GETAPIVERSION Return the API server version string.
            [status, body] = obj.request('GET', [obj.BaseUrl '/version']);
            assert(status == 200, 'EventStudyAPI:version', ...
                '/version returned HTTP %d', status);
            v = jsondecode(body).version;
        end

        function token = authenticate(obj)
            %AUTHENTICATE Create a task and store its token.
            payload = obj.apiPost('/task/create', ...
                {'X-Customer-Key', obj.ApiKey}, [], ...
                'application/json', 'authenticate');
            if ~isfield(payload, 'token') || isempty(payload.token)
                error('EventStudyAPI:auth', ...
                    'authenticate: no token in response; check your API key');
            end
            obj.Token = payload.token;
            token = obj.Token;
        end

        function configure(obj, params)
            %CONFIGURE Send the task configuration (/task/conf).
            obj.requireToken();
            obj.apiPost('/task/conf', {'X-Task-Key', obj.Token}, ...
                uint8(jsonencode(rmfield(params, 'file_keys'))), ...
                'application/json', 'configure');
        end

        function upload(obj, fileKey, path)
            %UPLOAD Upload one input file as a raw request body.
            obj.requireToken();
            fid = fopen(path, 'rb');
            assert(fid > 0, 'EventStudyAPI:file', ...
                'input file not found: %s', path);
            bytes = fread(fid, Inf, '*uint8')';
            fclose(fid);
            obj.apiPost(sprintf('/task/content/%s/0', fileKey), ...
                {'X-Task-Key', obj.Token}, bytes, ...
                'application/octet-stream', ['upload ' fileKey]);
        end

        function commit(obj)
            %COMMIT Server-side validation of configuration and data.
            obj.requireToken();
            obj.apiPost('/task/commit', {'X-Task-Key', obj.Token}, [], ...
                'application/json', 'commit');
        end

        function results = process(obj)
            %PROCESS Launch the calculation; returns announced files.
            obj.requireToken();
            payload = obj.apiPost('/task/process', ...
                {'X-Task-Key', obj.Token}, [], ...
                'application/json', 'process');
            assert(isfield(payload, 'results') && ~isempty(payload.results), ...
                'EventStudyAPI:process', 'no result files announced');
            obj.ResultFiles = payload.results(:)';
            results = obj.ResultFiles;
        end

        function results = downloadResults(obj, destDir, deadline)
            %DOWNLOADRESULTS Poll until done, then download all files.
            if nargin < 2, destDir = 'results'; end
            if nargin < 3, deadline = 600; end
            assert(~isempty(obj.ResultFiles), 'EventStudyAPI:order', ...
                'no result files; call process() first');
            if ~exist(destDir, 'dir'), mkdir(destDir); end

            waited = 0; status = -1;
            while waited <= deadline
                status = obj.request('GET', obj.ResultFiles(1).url);
                if status == 200, break; end
                pause(2); waited = waited + 2;
            end
            assert(status == 200, 'EventStudyAPI:timeout', ...
                'results not ready after %ds (last HTTP %d)', ...
                deadline, status);

            for i = 1:numel(obj.ResultFiles)
                [status, body] = obj.request('GET', obj.ResultFiles(i).url);
                assert(status == 200, 'EventStudyAPI:download', ...
                    'download %s: HTTP %d', obj.ResultFiles(i).basename, ...
                    status);
                local = fullfile(destDir, obj.ResultFiles(i).basename);
                fid = fopen(local, 'wb');
                fwrite(fid, body);
                fclose(fid);
                obj.ResultFiles(i).local_path = local;
            end
            results = obj.ResultFiles;
        end

        function results = run(obj, params, files, destDir, deadline)
            %RUN Perform a complete event study in one call.
            %   params  - struct from EventStudyAPI.arcParams() etc.
            %   files   - struct mapping file keys to local paths
            %   destDir - directory for result files (default 'results')
            if nargin < 4, destDir = 'results'; end
            if nargin < 5, deadline = 600; end
            keys = params.file_keys;
            for i = 1:numel(keys)
                assert(isfield(files, keys{i}), 'EventStudyAPI:files', ...
                    'missing input file: %s', keys{i});
            end
            obj.authenticate();
            obj.configure(params);
            for i = 1:numel(keys)
                obj.upload(keys{i}, files.(keys{i}));
            end
            obj.commit();
            obj.process();
            results = obj.downloadResults(destDir, deadline);
        end
    end

    methods (Static)
        function params = arcParams(varargin)
            %ARCPARAMS Configuration for the abnormal-return calculator.
            %   Name-value options: BenchmarkModel (mm), ReturnType (log),
            %   NonTradingDays (later), ResultFileType (csv),
            %   TestStatistics (cellstr), Email, Locale (en).
            params = EventStudyAPI.axcParams('arc', ...
                {'mm', 'mm-sw', 'mam', 'cpmam', 'ff3fm', 'ffm4fm', ...
                 'ff5fm', 'garch', 'egarch', 'capm'}, 'mm', varargin{:});
        end

        function params = avcParams(varargin)
            %AVCPARAMS Configuration for the abnormal-volume calculator.
            params = EventStudyAPI.axcParams('avc', ...
                {'mm', 'mm-sw', 'mam', 'cpmam', 'cmm'}, 'mm', varargin{:});
        end

        function params = avycParams(varargin)
            %AVYCPARAMS Configuration for the abnormal-volatility calculator.
            params = EventStudyAPI.axcParams('avyc', {'garch'}, ...
                'garch', varargin{:});
        end

        function stats = testStatistics()
            %TESTSTATISTICS All valid test statistic codes.
            stats = {'art', 'cart', 'aart', 'caart', 'abhart', ...
                'aarptlz', 'caarptlz', 'aaraptlz', 'caaraptlz', ...
                'aarbmpz', 'caarbmpz', 'aarabmpz', 'caarabmpz', ...
                'aarskewadjt', 'caarskewadjt', 'abharskewadjt', ...
                'aarrankz', 'caarrankz', 'aargrankt', 'caargrankt', ...
                'aargrankz', 'caargrankz', 'aargsignz', 'caargsignz'};
        end
    end

    methods (Static, Access = private)
        function params = axcParams(appKey, validModels, defaultModel, varargin)
            p = inputParser;
            addParameter(p, 'BenchmarkModel', defaultModel, ...
                @(x) any(strcmp(x, validModels)));
            addParameter(p, 'ReturnType', 'log', ...
                @(x) any(strcmp(x, {'log', 'simple'})));
            addParameter(p, 'NonTradingDays', 'later', ...
                @(x) any(strcmp(x, {'later', 'earlier', 'keep', 'skip'})));
            addParameter(p, 'ResultFileType', 'csv', ...
                @(x) any(strcmp(x, {'csv', 'xls', 'xlsx', 'ods'})));
            addParameter(p, 'TestStatistics', ...
                {'aart', 'caart', 'aarptlz', 'caarptlz', ...
                 'aarbmpz', 'caarbmpz'}, @iscellstr);
            addParameter(p, 'Email', '', @ischar);
            addParameter(p, 'Locale', 'en', @ischar);
            parse(p, varargin{:});
            r = p.Results;

            unknown = setdiff(r.TestStatistics, ...
                EventStudyAPI.testStatistics());
            assert(isempty(unknown), 'EventStudyAPI:params', ...
                'unknown test statistics: %s', strjoin(unknown, ', '));

            task = struct('locale', r.Locale);
            if ~isempty(r.Email), task.email = r.Email; end
            fileKeys = {'request_file', 'firm_data', 'market_data'};
            params = struct( ...
                'task', task, ...
                'application', struct( ...
                    'key', appKey, ...
                    'data_sources', struct( ...
                        'key', fileKeys, ...
                        'type', {'csv', 'csv', 'csv'}, ...
                        'hash', {'', '', ''})), ...
                'parameters', struct( ...
                    'return_type', r.ReturnType, ...
                    'result_file_type', r.ResultFileType, ...
                    'non_trading_days', r.NonTradingDays, ...
                    'benchmark_model', r.BenchmarkModel, ...
                    'regression_method', 'ols', ...
                    'test_statistics', {r.TestStatistics}), ...
                'file_keys', {fileKeys});
        end
    end

    methods (Access = private)
        function requireToken(obj)
            assert(~isempty(obj.Token), 'EventStudyAPI:order', ...
                'not authenticated; call authenticate() first');
        end

        function [status, body] = request(obj, method, url, headers, payload, contentType)
            %REQUEST Send one HTTP request; returns status and char body.
            import matlab.net.http.RequestMessage
            import matlab.net.http.HeaderField
            import matlab.net.http.MessageBody
            if nargin < 4, headers = {}; end
            if nargin < 5, payload = []; end
            if nargin < 6, contentType = ''; end

            fields = HeaderField('User-Agent', EventStudyAPI.UserAgent);
            for i = 1:2:numel(headers)
                fields(end+1) = HeaderField(headers{i}, headers{i+1}); %#ok<AGROW>
            end
            if ~isempty(contentType)
                fields(end+1) = HeaderField('Content-Type', contentType);
            end

            req = RequestMessage(method, fields);
            if ~isempty(payload)
                req.Body = MessageBody(payload);
                % keep the payload bytes exactly as passed
                req.Body.Payload = payload;
            end
            options = matlab.net.http.HTTPOptions('ConnectTimeout', 60);
            resp = req.send(matlab.net.URI(url), options);
            status = double(resp.StatusCode);
            data = resp.Body.Data;
            if ischar(data)
                body = data;
            elseif isstring(data)
                body = char(data);
            elseif isa(data, 'uint8')
                body = native2unicode(data', 'UTF-8');
            else
                body = char(jsonencode(data));  % pre-decoded JSON
            end
        end

        function payload = apiPost(obj, path, headers, body, contentType, step)
            %APIPOST POST to the API server and decode/validate the reply.
            if isempty(body)
                body = uint8('');
            end
            [status, text] = obj.request('POST', [obj.BaseUrl path], ...
                headers, body, contentType);
            if ~isempty(text) && text(1) == '<'
                error('EventStudyAPI:http', ...
                    '%s: unexpected HTML response (HTTP %d)', step, status);
            end
            try
                payload = jsondecode(text);
            catch
                error('EventStudyAPI:http', ...
                    '%s: invalid response (HTTP %d): %s', step, status, ...
                    text(1:min(end, 200)));
            end
            if isstruct(payload) && isfield(payload, 'error')
                error('EventStudyAPI:api', '%s: %s', step, payload.error);
            end
            if status ~= 200
                error('EventStudyAPI:http', '%s: HTTP %d: %s', ...
                    step, status, text(1:min(end, 200)));
            end
        end
    end
end