@primitivedotdev/sdk 0.2.4 → 0.4.0

package/README.md

@@ -2,13 +2,17 @@
 
 Official Primitive Node.js SDK.
 
-This package ships three Node.js modules:
+This package ships five Node.js modules and one CLI:
 
 - `@primitivedotdev/sdk` for the webhook module
+- `@primitivedotdev/sdk/api` for the generated HTTP API client
+- `@primitivedotdev/sdk/openapi` for the canonical OpenAPI document export
 - `@primitivedotdev/sdk/contract` for the contract module
 - `@primitivedotdev/sdk/parser` for the parser module
 
-`contract` and `parser` are only available in the Node SDK. The Go and Python SDKs expose the webhook surface only.
+It also publishes the `primitive` CLI bin from the same package.
+
+`contract`, `parser`, and `openapi` are Node-only extras. The Go and Python SDKs expose `webhook` and `api` modules.
 
 ## Requirements
 
@@ -65,6 +69,52 @@ Webhook exports include:
 - `WEBHOOK_VERSION`
 - webhook error classes and webhook types
 
+### API
+
+Use the API module for outbound calls to the Primitive HTTP API.
+
+```ts
+import { PrimitiveApiClient, getAccount } from "@primitivedotdev/sdk/api";
+
+const api = new PrimitiveApiClient({ apiKey: process.env.PRIMITIVE_API_KEY });
+const result = await getAccount({ client: api.client });
+
+if (result.error) {
+  throw result.error;
+}
+
+console.log(result.data.id);
+```
+
+The package also ships a generated CLI bin named `primitive`.
+
+### OpenAPI
+
+Use the OpenAPI module when another JavaScript application needs the canonical Primitive API spec.
+
+```ts
+import { openapiDocument } from "@primitivedotdev/sdk/openapi";
+
+console.log(openapiDocument.openapi);
+```
+
+### CLI
+
+Use the published `primitive` CLI for outbound API access from the terminal.
+
+```bash
+primitive --help
+primitive account get-account --api-key prim_test
+primitive emails download-raw-email --id <uuid> --api-key prim_test --output email.eml
+```
+
+Autocomplete support is available through:
+
+- `primitive completion fish`
+- `primitive completion bash`
+- `primitive completion zsh`
+- `primitive completion powershell`
+
 ### Contract
 
 Use the contract module when constructing canonical Primitive webhook payloads on the producer side.
@@ -199,10 +249,23 @@ make node-build
 
 ```text
 sdk-node/
+  bin/
+    run.js
   src/
+    api/
+      generated/
+      index.ts
     contract/
       contract.ts
       index.ts
+    oclif/
+      api-command.ts
+      fish-completion.ts
+      index.ts
+    openapi/
+      index.ts
+      openapi.generated.ts
+      operations.generated.ts
     parser/
       attachment-bundler.ts
       attachment-parser.ts

package/bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { execute } from "@oclif/core";
+
+await execute({ dir: import.meta.url });

package/dist/api/generated/client/client.gen.js

@@ -0,0 +1,235 @@
+// This file is auto-generated by @hey-api/openapi-ts
+import { createSseClient } from '../core/serverSentEvents.gen.js';
+import { getValidRequestBody } from '../core/utils.gen.js';
+import { buildUrl, createConfig, createInterceptors, getParseAs, mergeConfigs, mergeHeaders, setAuthParams, } from './utils.gen.js';
+export const createClient = (config = {}) => {
+    let _config = mergeConfigs(createConfig(), config);
+    const getConfig = () => ({ ..._config });
+    const setConfig = (config) => {
+        _config = mergeConfigs(_config, config);
+        return getConfig();
+    };
+    const interceptors = createInterceptors();
+    const beforeRequest = async (options) => {
+        const opts = {
+            ..._config,
+            ...options,
+            fetch: options.fetch ?? _config.fetch ?? globalThis.fetch,
+            headers: mergeHeaders(_config.headers, options.headers),
+            serializedBody: undefined,
+        };
+        if (opts.security) {
+            await setAuthParams({
+                ...opts,
+                security: opts.security,
+            });
+        }
+        if (opts.requestValidator) {
+            await opts.requestValidator(opts);
+        }
+        if (opts.body !== undefined && opts.bodySerializer) {
+            opts.serializedBody = opts.bodySerializer(opts.body);
+        }
+        // remove Content-Type header if body is empty to avoid sending invalid requests
+        if (opts.body === undefined || opts.serializedBody === '') {
+            opts.headers.delete('Content-Type');
+        }
+        const resolvedOpts = opts;
+        const url = buildUrl(resolvedOpts);
+        return { opts: resolvedOpts, url };
+    };
+    const request = async (options) => {
+        const { opts, url } = await beforeRequest(options);
+        const requestInit = {
+            redirect: 'follow',
+            ...opts,
+            body: getValidRequestBody(opts),
+        };
+        let request = new Request(url, requestInit);
+        for (const fn of interceptors.request.fns) {
+            if (fn) {
+                request = await fn(request, opts);
+            }
+        }
+        // fetch must be assigned here, otherwise it would throw the error:
+        // TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation
+        const _fetch = opts.fetch;
+        let response;
+        try {
+            response = await _fetch(request);
+        }
+        catch (error) {
+            // Handle fetch exceptions (AbortError, network errors, etc.)
+            let finalError = error;
+            for (const fn of interceptors.error.fns) {
+                if (fn) {
+                    finalError = (await fn(error, undefined, request, opts));
+                }
+            }
+            finalError = finalError || {};
+            if (opts.throwOnError) {
+                throw finalError;
+            }
+            // Return error response
+            return opts.responseStyle === 'data'
+                ? undefined
+                : {
+                    error: finalError,
+                    request,
+                    response: undefined,
+                };
+        }
+        for (const fn of interceptors.response.fns) {
+            if (fn) {
+                response = await fn(response, request, opts);
+            }
+        }
+        const result = {
+            request,
+            response,
+        };
+        if (response.ok) {
+            const parseAs = (opts.parseAs === 'auto'
+                ? getParseAs(response.headers.get('Content-Type'))
+                : opts.parseAs) ?? 'json';
+            if (response.status === 204 || response.headers.get('Content-Length') === '0') {
+                let emptyData;
+                switch (parseAs) {
+                    case 'arrayBuffer':
+                    case 'blob':
+                    case 'text':
+                        emptyData = await response[parseAs]();
+                        break;
+                    case 'formData':
+                        emptyData = new FormData();
+                        break;
+                    case 'stream':
+                        emptyData = response.body;
+                        break;
+                    case 'json':
+                    default:
+                        emptyData = {};
+                        break;
+                }
+                return opts.responseStyle === 'data'
+                    ? emptyData
+                    : {
+                        data: emptyData,
+                        ...result,
+                    };
+            }
+            let data;
+            switch (parseAs) {
+                case 'arrayBuffer':
+                case 'blob':
+                case 'formData':
+                case 'text':
+                    data = await response[parseAs]();
+                    break;
+                case 'json': {
+                    // Some servers return 200 with no Content-Length and empty body.
+                    // response.json() would throw; read as text and parse if non-empty.
+                    const text = await response.text();
+                    data = text ? JSON.parse(text) : {};
+                    break;
+                }
+                case 'stream':
+                    return opts.responseStyle === 'data'
+                        ? response.body
+                        : {
+                            data: response.body,
+                            ...result,
+                        };
+            }
+            if (parseAs === 'json') {
+                if (opts.responseValidator) {
+                    await opts.responseValidator(data);
+                }
+                if (opts.responseTransformer) {
+                    data = await opts.responseTransformer(data);
+                }
+            }
+            return opts.responseStyle === 'data'
+                ? data
+                : {
+                    data,
+                    ...result,
+                };
+        }
+        const textError = await response.text();
+        let jsonError;
+        try {
+            jsonError = JSON.parse(textError);
+        }
+        catch {
+            // noop
+        }
+        const error = jsonError ?? textError;
+        let finalError = error;
+        for (const fn of interceptors.error.fns) {
+            if (fn) {
+                finalError = (await fn(error, response, request, opts));
+            }
+        }
+        finalError = finalError || {};
+        if (opts.throwOnError) {
+            throw finalError;
+        }
+        // TODO: we probably want to return error and improve types
+        return opts.responseStyle === 'data'
+            ? undefined
+            : {
+                error: finalError,
+                ...result,
+            };
+    };
+    const makeMethodFn = (method) => (options) => request({ ...options, method });
+    const makeSseFn = (method) => async (options) => {
+        const { opts, url } = await beforeRequest(options);
+        return createSseClient({
+            ...opts,
+            body: opts.body,
+            headers: opts.headers,
+            method,
+            onRequest: async (url, init) => {
+                let request = new Request(url, init);
+                for (const fn of interceptors.request.fns) {
+                    if (fn) {
+                        request = await fn(request, opts);
+                    }
+                }
+                return request;
+            },
+            serializedBody: getValidRequestBody(opts),
+            url,
+        });
+    };
+    const _buildUrl = (options) => buildUrl({ ..._config, ...options });
+    return {
+        buildUrl: _buildUrl,
+        connect: makeMethodFn('CONNECT'),
+        delete: makeMethodFn('DELETE'),
+        get: makeMethodFn('GET'),
+        getConfig,
+        head: makeMethodFn('HEAD'),
+        interceptors,
+        options: makeMethodFn('OPTIONS'),
+        patch: makeMethodFn('PATCH'),
+        post: makeMethodFn('POST'),
+        put: makeMethodFn('PUT'),
+        request,
+        setConfig,
+        sse: {
+            connect: makeSseFn('CONNECT'),
+            delete: makeSseFn('DELETE'),
+            get: makeSseFn('GET'),
+            head: makeSseFn('HEAD'),
+            options: makeSseFn('OPTIONS'),
+            patch: makeSseFn('PATCH'),
+            post: makeSseFn('POST'),
+            put: makeSseFn('PUT'),
+            trace: makeSseFn('TRACE'),
+        },
+        trace: makeMethodFn('TRACE'),
+    };
+};

package/dist/api/generated/client/index.js

@@ -0,0 +1,6 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export { formDataBodySerializer, jsonBodySerializer, urlSearchParamsBodySerializer, } from '../core/bodySerializer.gen.js';
+export { buildClientParams } from '../core/params.gen.js';
+export { serializeQueryKeyValue } from '../core/queryKeySerializer.gen.js';
+export { createClient } from './client.gen.js';
+export { createConfig, mergeHeaders } from './utils.gen.js';

package/dist/api/generated/client/types.gen.js

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};

package/dist/api/generated/client/utils.gen.js

@@ -0,0 +1,228 @@
+// This file is auto-generated by @hey-api/openapi-ts
+import { getAuthToken } from '../core/auth.gen.js';
+import { jsonBodySerializer } from '../core/bodySerializer.gen.js';
+import { serializeArrayParam, serializeObjectParam, serializePrimitiveParam, } from '../core/pathSerializer.gen.js';
+import { getUrl } from '../core/utils.gen.js';
+export const createQuerySerializer = ({ parameters = {}, ...args } = {}) => {
+    const querySerializer = (queryParams) => {
+        const search = [];
+        if (queryParams && typeof queryParams === 'object') {
+            for (const name in queryParams) {
+                const value = queryParams[name];
+                if (value === undefined || value === null) {
+                    continue;
+                }
+                const options = parameters[name] || args;
+                if (Array.isArray(value)) {
+                    const serializedArray = serializeArrayParam({
+                        allowReserved: options.allowReserved,
+                        explode: true,
+                        name,
+                        style: 'form',
+                        value,
+                        ...options.array,
+                    });
+                    if (serializedArray)
+                        search.push(serializedArray);
+                }
+                else if (typeof value === 'object') {
+                    const serializedObject = serializeObjectParam({
+                        allowReserved: options.allowReserved,
+                        explode: true,
+                        name,
+                        style: 'deepObject',
+                        value: value,
+                        ...options.object,
+                    });
+                    if (serializedObject)
+                        search.push(serializedObject);
+                }
+                else {
+                    const serializedPrimitive = serializePrimitiveParam({
+                        allowReserved: options.allowReserved,
+                        name,
+                        value: value,
+                    });
+                    if (serializedPrimitive)
+                        search.push(serializedPrimitive);
+                }
+            }
+        }
+        return search.join('&');
+    };
+    return querySerializer;
+};
+/**
+ * Infers parseAs value from provided Content-Type header.
+ */
+export const getParseAs = (contentType) => {
+    if (!contentType) {
+        // If no Content-Type header is provided, the best we can do is return the raw response body,
+        // which is effectively the same as the 'stream' option.
+        return 'stream';
+    }
+    const cleanContent = contentType.split(';')[0]?.trim();
+    if (!cleanContent) {
+        return;
+    }
+    if (cleanContent.startsWith('application/json') || cleanContent.endsWith('+json')) {
+        return 'json';
+    }
+    if (cleanContent === 'multipart/form-data') {
+        return 'formData';
+    }
+    if (['application/', 'audio/', 'image/', 'video/'].some((type) => cleanContent.startsWith(type))) {
+        return 'blob';
+    }
+    if (cleanContent.startsWith('text/')) {
+        return 'text';
+    }
+    return;
+};
+const checkForExistence = (options, name) => {
+    if (!name) {
+        return false;
+    }
+    if (options.headers.has(name) ||
+        options.query?.[name] ||
+        options.headers.get('Cookie')?.includes(`${name}=`)) {
+        return true;
+    }
+    return false;
+};
+export const setAuthParams = async ({ security, ...options }) => {
+    for (const auth of security) {
+        if (checkForExistence(options, auth.name)) {
+            continue;
+        }
+        const token = await getAuthToken(auth, options.auth);
+        if (!token) {
+            continue;
+        }
+        const name = auth.name ?? 'Authorization';
+        switch (auth.in) {
+            case 'query':
+                if (!options.query) {
+                    options.query = {};
+                }
+                options.query[name] = token;
+                break;
+            case 'cookie':
+                options.headers.append('Cookie', `${name}=${token}`);
+                break;
+            case 'header':
+            default:
+                options.headers.set(name, token);
+                break;
+        }
+    }
+};
+export const buildUrl = (options) => getUrl({
+    baseUrl: options.baseUrl,
+    path: options.path,
+    query: options.query,
+    querySerializer: typeof options.querySerializer === 'function'
+        ? options.querySerializer
+        : createQuerySerializer(options.querySerializer),
+    url: options.url,
+});
+export const mergeConfigs = (a, b) => {
+    const config = { ...a, ...b };
+    if (config.baseUrl?.endsWith('/')) {
+        config.baseUrl = config.baseUrl.substring(0, config.baseUrl.length - 1);
+    }
+    config.headers = mergeHeaders(a.headers, b.headers);
+    return config;
+};
+const headersEntries = (headers) => {
+    const entries = [];
+    headers.forEach((value, key) => {
+        entries.push([key, value]);
+    });
+    return entries;
+};
+export const mergeHeaders = (...headers) => {
+    const mergedHeaders = new Headers();
+    for (const header of headers) {
+        if (!header) {
+            continue;
+        }
+        const iterator = header instanceof Headers ? headersEntries(header) : Object.entries(header);
+        for (const [key, value] of iterator) {
+            if (value === null) {
+                mergedHeaders.delete(key);
+            }
+            else if (Array.isArray(value)) {
+                for (const v of value) {
+                    mergedHeaders.append(key, v);
+                }
+            }
+            else if (value !== undefined) {
+                // assume object headers are meant to be JSON stringified, i.e., their
+                // content value in OpenAPI specification is 'application/json'
+                mergedHeaders.set(key, typeof value === 'object' ? JSON.stringify(value) : value);
+            }
+        }
+    }
+    return mergedHeaders;
+};
+class Interceptors {
+    fns = [];
+    clear() {
+        this.fns = [];
+    }
+    eject(id) {
+        const index = this.getInterceptorIndex(id);
+        if (this.fns[index]) {
+            this.fns[index] = null;
+        }
+    }
+    exists(id) {
+        const index = this.getInterceptorIndex(id);
+        return Boolean(this.fns[index]);
+    }
+    getInterceptorIndex(id) {
+        if (typeof id === 'number') {
+            return this.fns[id] ? id : -1;
+        }
+        return this.fns.indexOf(id);
+    }
+    update(id, fn) {
+        const index = this.getInterceptorIndex(id);
+        if (this.fns[index]) {
+            this.fns[index] = fn;
+            return id;
+        }
+        return false;
+    }
+    use(fn) {
+        this.fns.push(fn);
+        return this.fns.length - 1;
+    }
+}
+export const createInterceptors = () => ({
+    error: new Interceptors(),
+    request: new Interceptors(),
+    response: new Interceptors(),
+});
+const defaultQuerySerializer = createQuerySerializer({
+    allowReserved: false,
+    array: {
+        explode: true,
+        style: 'form',
+    },
+    object: {
+        explode: true,
+        style: 'deepObject',
+    },
+});
+const defaultHeaders = {
+    'Content-Type': 'application/json',
+};
+export const createConfig = (override = {}) => ({
+    ...jsonBodySerializer,
+    headers: defaultHeaders,
+    parseAs: 'auto',
+    querySerializer: defaultQuerySerializer,
+    ...override,
+});

package/dist/api/generated/client.gen.js

@@ -0,0 +1,3 @@
+// This file is auto-generated by @hey-api/openapi-ts
+import { createClient, createConfig } from './client/index.js';
+export const client = createClient(createConfig({ baseUrl: 'https://www.primitive.dev/api/v1' }));

package/dist/api/generated/core/auth.gen.js

@@ -0,0 +1,14 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export const getAuthToken = async (auth, callback) => {
+    const token = typeof callback === 'function' ? await callback(auth) : callback;
+    if (!token) {
+        return;
+    }
+    if (auth.scheme === 'bearer') {
+        return `Bearer ${token}`;
+    }
+    if (auth.scheme === 'basic') {
+        return `Basic ${btoa(token)}`;
+    }
+    return token;
+};

package/dist/api/generated/core/bodySerializer.gen.js

@@ -0,0 +1,57 @@
+// This file is auto-generated by @hey-api/openapi-ts
+const serializeFormDataPair = (data, key, value) => {
+    if (typeof value === 'string' || value instanceof Blob) {
+        data.append(key, value);
+    }
+    else if (value instanceof Date) {
+        data.append(key, value.toISOString());
+    }
+    else {
+        data.append(key, JSON.stringify(value));
+    }
+};
+const serializeUrlSearchParamsPair = (data, key, value) => {
+    if (typeof value === 'string') {
+        data.append(key, value);
+    }
+    else {
+        data.append(key, JSON.stringify(value));
+    }
+};
+export const formDataBodySerializer = {
+    bodySerializer: (body) => {
+        const data = new FormData();
+        Object.entries(body).forEach(([key, value]) => {
+            if (value === undefined || value === null) {
+                return;
+            }
+            if (Array.isArray(value)) {
+                value.forEach((v) => serializeFormDataPair(data, key, v));
+            }
+            else {
+                serializeFormDataPair(data, key, value);
+            }
+        });
+        return data;
+    },
+};
+export const jsonBodySerializer = {
+    bodySerializer: (body) => JSON.stringify(body, (_key, value) => (typeof value === 'bigint' ? value.toString() : value)),
+};
+export const urlSearchParamsBodySerializer = {
+    bodySerializer: (body) => {
+        const data = new URLSearchParams();
+        Object.entries(body).forEach(([key, value]) => {
+            if (value === undefined || value === null) {
+                return;
+            }
+            if (Array.isArray(value)) {
+                value.forEach((v) => serializeUrlSearchParamsPair(data, key, v));
+            }
+            else {
+                serializeUrlSearchParamsPair(data, key, value);
+            }
+        });
+        return data.toString();
+    },
+};