@myapihq/sdk 2.4.1 → 2.4.2

package/dist/client.d.ts

@@ -5,10 +5,31 @@ export declare class MyApiError extends Error {
     body?: Record<string, unknown> | undefined;
     constructor(code: string, status: number, detail?: string | undefined, body?: Record<string, unknown> | undefined);
 }
-export declare function request<T>(method: string, url: string, apiKey?: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+/**
+ * Identify the calling client in the User-Agent. The CLI calls this at startup
+ * with its own version; SDK-only consumers can call it to tag their app. Note
+ * that browsers silently drop a caller-set User-Agent — that's expected.
+ */
+export declare function setUserAgent(ua: string): void;
+export interface RequestOptions {
+    /** Per-attempt deadline in ms. 0 disables. Default 120s, or MYAPI_TIMEOUT_MS. */
+    timeoutMs?: number;
+    /** Total attempts including the first. Default 3, or MYAPI_MAX_ATTEMPTS. */
+    maxAttempts?: number;
+    /**
+     * Retry non-idempotent methods (POST/PATCH) too. OFF by default: the SDK
+     * sends an Idempotency-Key on every mutating call, but until the backend
+     * honors it a retried POST is a duplicate charge / duplicate send. Flip this
+     * per-call only for endpoints confirmed to deduplicate.
+     */
+    retryUnsafe?: boolean;
+    /** Caller-supplied AbortSignal, composed with the timeout. */
+    signal?: AbortSignal;
+}
+export declare function request<T>(method: string, url: string, apiKey?: string, body?: unknown, extraHeaders?: Record<string, string>, opts?: RequestOptions): Promise<T>;
 export interface Page<T> {
     data: T[];
     next_cursor?: string;
     has_more?: boolean;
 }
-export declare function requestPage<T>(method: string, url: string, apiKey?: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<Page<T>>;
+export declare function requestPage<T>(method: string, url: string, apiKey?: string, body?: unknown, extraHeaders?: Record<string, string>, opts?: RequestOptions): Promise<Page<T>>;

package/dist/client.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MyApiError = void 0;
+exports.setUserAgent = setUserAgent;
 exports.request = request;
 exports.requestPage = requestPage;
+const version_1 = require("./version");
 class MyApiError extends Error {
     code;
     status;
@@ -23,7 +25,121 @@ class MyApiError extends Error {
     }
 }
 exports.MyApiError = MyApiError;
-async function requestFull(method, url, apiKey, body, extraHeaders) {
+// ---------------------------------------------------------------------------
+// Transport policy
+// ---------------------------------------------------------------------------
+// Every call in this SDK is a single `fetch`. Without a deadline that means a
+// hung edge hop hangs the caller forever — and the caller is usually an agent
+// in a loop with no way to notice. These knobs bound that.
+/** Per-attempt deadline. Generous on purpose: bound hangs, don't fight slow
+ *  but healthy calls (LLM completions, multi-file funnel publishes). */
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** Total attempts, not retries — 3 means at most 2 retries. */
+const DEFAULT_MAX_ATTEMPTS = 3;
+const BACKOFF_BASE_MS = 250;
+const BACKOFF_CAP_MS = 8_000;
+// Transient by definition: the request never reached a handler, or the
+// handler explicitly asked us to come back. 500 is deliberately absent —
+// it's ambiguous (the write may have landed), so retrying it can duplicate.
+const RETRYABLE_STATUS = new Set([408, 429, 502, 503, 504]);
+// Retrying these is safe by HTTP semantics regardless of backend support.
+const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']);
+// Methods that mutate and therefore get an Idempotency-Key, so the backend
+// can collapse duplicates once it honors the header.
+const KEYED_METHODS = new Set(['POST', 'PATCH', 'PUT']);
+function env(name) {
+    // Guarded: `process` is absent in some edge/browser runtimes.
+    try {
+        return typeof process !== 'undefined' ? process.env?.[name] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function envInt(name, fallback) {
+    const raw = env(name);
+    if (raw === undefined || raw === '')
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+let configuredUserAgent;
+/**
+ * Identify the calling client in the User-Agent. The CLI calls this at startup
+ * with its own version; SDK-only consumers can call it to tag their app. Note
+ * that browsers silently drop a caller-set User-Agent — that's expected.
+ */
+function setUserAgent(ua) {
+    configuredUserAgent = ua;
+}
+function userAgent() {
+    return configuredUserAgent ?? env('MYAPI_USER_AGENT') ?? `myapihq-sdk/${version_1.SDK_VERSION}`;
+}
+function newIdempotencyKey() {
+    const c = typeof globalThis !== 'undefined' ? globalThis.crypto : undefined;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    if (c?.getRandomValues) {
+        const b = c.getRandomValues(new Uint8Array(16));
+        return Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+    }
+    // Last resort. Only reached on runtimes with no Web Crypto at all; the key
+    // still just needs to be unique per logical request, not unguessable.
+    return `${Date.now().toString(16)}-${Math.random().toString(16).slice(2)}`;
+}
+/** Parse Retry-After, which is either delta-seconds or an HTTP-date. */
+function retryAfterMs(header) {
+    if (!header)
+        return undefined;
+    const secs = Number(header);
+    if (Number.isFinite(secs))
+        return Math.max(0, secs * 1000);
+    const when = Date.parse(header);
+    if (!Number.isNaN(when))
+        return Math.max(0, when - Date.now());
+    return undefined;
+}
+/** Exponential backoff with full jitter — spreads a thundering herd of agents
+ *  retrying the same rate-limited endpoint instead of resynchronising them. */
+function backoffMs(attempt) {
+    const ceiling = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** (attempt - 1));
+    return Math.random() * ceiling;
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function isAbortError(e) {
+    return !!e && typeof e === 'object' && e.name === 'AbortError';
+}
+async function fetchOnce(method, url, headers, body, timeoutMs, callerSignal) {
+    const options = { method, headers };
+    if (body !== undefined)
+        options.body = body;
+    // No timeout configured and no caller signal — nothing to wire up.
+    if (timeoutMs <= 0 && !callerSignal)
+        return fetch(url, options);
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    let timer;
+    if (timeoutMs > 0)
+        timer = setTimeout(() => controller.abort(), timeoutMs);
+    if (callerSignal) {
+        if (callerSignal.aborted)
+            controller.abort();
+        else
+            callerSignal.addEventListener('abort', onAbort, { once: true });
+    }
+    options.signal = controller.signal;
+    try {
+        return await fetch(url, options);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        callerSignal?.removeEventListener('abort', onAbort);
+    }
+}
+async function requestFull(method, url, apiKey, body, extraHeaders, opts) {
     const headers = {};
     if (apiKey) {
         headers['Authorization'] = `Bearer ${apiKey}`;
@@ -31,6 +147,13 @@ async function requestFull(method, url, apiKey, body, extraHeaders) {
     if (body !== undefined) {
         headers['Content-Type'] = 'application/json';
     }
+    headers['User-Agent'] = userAgent();
+    const upper = method.toUpperCase();
+    // One key for the whole call, reused across attempts — that's the entire
+    // point. Generating per-attempt would defeat deduplication.
+    if (KEYED_METHODS.has(upper) && !extraHeaders?.['Idempotency-Key']) {
+        headers['Idempotency-Key'] = newIdempotencyKey();
+    }
     // Caller-supplied headers (e.g. CAS via If-Match) win over the defaults
     // above. Keep this near the top so route logic later doesn't accidentally
     // overwrite something the caller passed in.
@@ -38,14 +161,45 @@ async function requestFull(method, url, apiKey, body, extraHeaders) {
         for (const [k, v] of Object.entries(extraHeaders))
             headers[k] = v;
     }
-    const options = {
-        method,
-        headers,
-    };
-    if (body !== undefined) {
-        options.body = JSON.stringify(body);
+    const payload = body !== undefined ? JSON.stringify(body) : undefined;
+    const timeoutMs = opts?.timeoutMs ?? envInt('MYAPI_TIMEOUT_MS', DEFAULT_TIMEOUT_MS);
+    const maxAttempts = Math.max(1, opts?.maxAttempts ?? envInt('MYAPI_MAX_ATTEMPTS', DEFAULT_MAX_ATTEMPTS));
+    const mayRetry = IDEMPOTENT_METHODS.has(upper) || opts?.retryUnsafe === true;
+    let attempt = 0;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        attempt++;
+        let response;
+        try {
+            response = await fetchOnce(upper, url, headers, payload, timeoutMs, opts?.signal);
+        }
+        catch (e) {
+            // The caller aborted deliberately — surface that, never retry it.
+            if (opts?.signal?.aborted) {
+                throw new MyApiError('request_aborted', 0, `${upper} ${url} was aborted by the caller`);
+            }
+            // Transport never produced a response: DNS failure, connection reset,
+            // TLS error, or our own timeout. Previously this escaped as a bare
+            // TypeError, which bypassed the CLI's friendlyError entirely.
+            const timedOut = isAbortError(e);
+            if (mayRetry && attempt < maxAttempts) {
+                await sleep(backoffMs(attempt));
+                continue;
+            }
+            if (timedOut) {
+                throw new MyApiError('timeout', 0, `${upper} ${url} timed out after ${timeoutMs}ms (attempt ${attempt} of ${maxAttempts})`);
+            }
+            throw new MyApiError('network_error', 0, `${upper} ${url} failed: ${e?.message ?? String(e)}`);
+        }
+        if (mayRetry && attempt < maxAttempts && RETRYABLE_STATUS.has(response.status)) {
+            const after = retryAfterMs(response.headers.get('retry-after'));
+            await sleep(after ?? backoffMs(attempt));
+            continue;
+        }
+        return await parseResponse(upper, url, response);
     }
-    const response = await fetch(url, options);
+}
+async function parseResponse(method, url, response) {
     if (response.status === 204) {
         return { success: true, data: null, error: null, meta: {} };
     }
@@ -62,31 +216,29 @@ async function requestFull(method, url, apiKey, body, extraHeaders) {
         throw new MyApiError('invalid_json_response', response.status, `${method} ${url} returned non-JSON (status ${response.status}): ${snippet}`);
     }
     if (!response.ok) {
-        const err = result?.error;
-        const code = typeof err === 'object' ? (err?.code || 'unknown_error') : (err || 'unknown_error');
-        const detail = typeof err === 'object' ? (err?.message || undefined) : undefined;
-        const errBody = typeof err === 'object' ? err : undefined;
-        throw new MyApiError(code, response.status, detail, errBody);
+        throw toError(result?.error, response.status);
     }
     const apiResponse = result;
     if (!apiResponse.success) {
-        const err = apiResponse.error;
-        const code = typeof err === 'object' ? (err?.code || 'unknown_error') : (err || 'unknown_error');
-        const detail = typeof err === 'object' ? (err?.message || undefined) : undefined;
-        const errBody = typeof err === 'object' ? err : undefined;
-        throw new MyApiError(code, response.status, detail, errBody);
+        throw toError(apiResponse.error, response.status);
     }
     return apiResponse;
 }
+function toError(err, status) {
+    const code = typeof err === 'object' && err !== null ? (err?.code || 'unknown_error') : (err || 'unknown_error');
+    const detail = typeof err === 'object' && err !== null ? (err?.message || undefined) : undefined;
+    const errBody = typeof err === 'object' && err !== null ? err : undefined;
+    return new MyApiError(code, status, detail, errBody);
+}
 // Returns the unwrapped `data` payload — the common case.
-async function request(method, url, apiKey, body, extraHeaders) {
-    return (await requestFull(method, url, apiKey, body, extraHeaders)).data;
+async function request(method, url, apiKey, body, extraHeaders, opts) {
+    return (await requestFull(method, url, apiKey, body, extraHeaders, opts)).data;
 }
 // For keyset-paginated endpoints (backend `envelope.WrapPage`): `data` is a
 // bare array and the cursor/has_more live under `meta`. `request` would drop
 // the cursor, so list endpoints with pagination must use this.
-async function requestPage(method, url, apiKey, body, extraHeaders) {
-    const r = await requestFull(method, url, apiKey, body, extraHeaders);
+async function requestPage(method, url, apiKey, body, extraHeaders, opts) {
+    const r = await requestFull(method, url, apiKey, body, extraHeaders, opts);
     const meta = (r.meta ?? {});
     return { data: (r.data ?? []), next_cursor: meta.next_cursor, has_more: meta.has_more };
 }

package/dist/crm.d.ts

@@ -111,6 +111,7 @@ export declare function createContact(apiKey: string, orgId: string, input: Crea
 export declare function getContact(apiKey: string, orgId: string, id: string): Promise<Contact>;
 export declare function updateContact(apiKey: string, orgId: string, id: string, patch: UpdateContactInput): Promise<Contact>;
 export declare function deleteContact(apiKey: string, orgId: string, id: string): Promise<void>;
+export declare function restoreContact(apiKey: string, orgId: string, id: string): Promise<Contact>;
 export declare function searchContacts(apiKey: string, orgId: string, filter?: ContactSearchFilter): Promise<ContactSearchResult>;
 export declare function promoteContact(apiKey: string, orgId: string, goldfoxPersonId: string): Promise<Contact>;
 export declare function getContactEvents(apiKey: string, orgId: string, id: string, opts?: ListEventsOptions): Promise<EventsResponse>;
@@ -118,5 +119,6 @@ export declare function createCompany(apiKey: string, orgId: string, input: Crea
 export declare function getCompany(apiKey: string, orgId: string, id: string): Promise<Company>;
 export declare function updateCompany(apiKey: string, orgId: string, id: string, patch: UpdateCompanyInput): Promise<Company>;
 export declare function deleteCompany(apiKey: string, orgId: string, id: string): Promise<void>;
+export declare function restoreCompany(apiKey: string, orgId: string, id: string): Promise<Company>;
 export declare function searchCompanies(apiKey: string, orgId: string, filter?: CompanySearchFilter): Promise<CompanySearchResult>;
 export declare function promoteCompany(apiKey: string, orgId: string, domain: string): Promise<Company>;

package/dist/crm.js

@@ -5,6 +5,7 @@ exports.createContact = createContact;
 exports.getContact = getContact;
 exports.updateContact = updateContact;
 exports.deleteContact = deleteContact;
+exports.restoreContact = restoreContact;
 exports.searchContacts = searchContacts;
 exports.promoteContact = promoteContact;
 exports.getContactEvents = getContactEvents;
@@ -12,6 +13,7 @@ exports.createCompany = createCompany;
 exports.getCompany = getCompany;
 exports.updateCompany = updateCompany;
 exports.deleteCompany = deleteCompany;
+exports.restoreCompany = restoreCompany;
 exports.searchCompanies = searchCompanies;
 exports.promoteCompany = promoteCompany;
 const client_1 = require("./client");
@@ -23,6 +25,7 @@ exports.EXPOSES = [
     'GET /crm/orgs/{org_id}/contacts/{id}',
     'PATCH /crm/orgs/{org_id}/contacts/{id}',
     'DELETE /crm/orgs/{org_id}/contacts/{id}',
+    'POST /crm/orgs/{org_id}/contacts/{id}/restore',
     'GET /crm/orgs/{org_id}/contacts/{id}/events',
     'POST /crm/orgs/{org_id}/companies',
     'POST /crm/orgs/{org_id}/companies/promote',
@@ -30,6 +33,7 @@ exports.EXPOSES = [
     'GET /crm/orgs/{org_id}/companies/{id}',
     'PATCH /crm/orgs/{org_id}/companies/{id}',
     'DELETE /crm/orgs/{org_id}/companies/{id}',
+    'POST /crm/orgs/{org_id}/companies/{id}/restore',
 ];
 // ── Contacts ──────────────────────────────────────────────────────────────
 async function createContact(apiKey, orgId, input) {
@@ -44,6 +48,13 @@ async function updateContact(apiKey, orgId, id, patch) {
 async function deleteContact(apiKey, orgId, id) {
     return (0, client_1.request)('DELETE', `${config_1.CRM_BASE}/crm/orgs/${encodeURIComponent(orgId)}/contacts/${encodeURIComponent(id)}`, apiKey);
 }
+// Undo a soft delete. Uses the backend's dedicated restore verb rather than
+// PATCHing `deleted_at: null` — the CLI used to do the latter, which quietly
+// depended on the update handler accepting a field that isn't part of the
+// documented update contract.
+async function restoreContact(apiKey, orgId, id) {
+    return (0, client_1.request)('POST', `${config_1.CRM_BASE}/crm/orgs/${encodeURIComponent(orgId)}/contacts/${encodeURIComponent(id)}/restore`, apiKey);
+}
 async function searchContacts(apiKey, orgId, filter = {}) {
     return (0, client_1.request)('POST', `${config_1.CRM_BASE}/crm/orgs/${encodeURIComponent(orgId)}/contacts/search`, apiKey, filter);
 }
@@ -78,6 +89,10 @@ async function updateCompany(apiKey, orgId, id, patch) {
 async function deleteCompany(apiKey, orgId, id) {
     return (0, client_1.request)('DELETE', `${config_1.CRM_BASE}/crm/orgs/${encodeURIComponent(orgId)}/companies/${encodeURIComponent(id)}`, apiKey);
 }
+// See restoreContact — same contract, companies half.
+async function restoreCompany(apiKey, orgId, id) {
+    return (0, client_1.request)('POST', `${config_1.CRM_BASE}/crm/orgs/${encodeURIComponent(orgId)}/companies/${encodeURIComponent(id)}/restore`, apiKey);
+}
 async function searchCompanies(apiKey, orgId, filter = {}) {
     return (0, client_1.request)('POST', `${config_1.CRM_BASE}/crm/orgs/${encodeURIComponent(orgId)}/companies/search`, apiKey, filter);
 }

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './types';
 export * from './client';
 export * from './funds';
+export * from './version';
 export * as hq from './hq';
 export * as auth from './auth';
 export * as domain from './domain';

package/dist/index.js

@@ -40,6 +40,7 @@ exports.task = exports.queue = exports.git = exports.container = exports.payment
 __exportStar(require("./types"), exports);
 __exportStar(require("./client"), exports);
 __exportStar(require("./funds"), exports);
+__exportStar(require("./version"), exports);
 // Note: config constants (STORAGE_BASE etc.) are NOT re-exported from the
 // barrel. TypeScript compiles `export * from './config'` to a runtime
 // `__exportStar` call that Node's cjs-module-lexer can't see through, so

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "2.4.2";

package/dist/version.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = void 0;
+// Kept in lockstep with package.json by scripts/release.mjs, and guarded by
+// packages/cli/src/sdk-version.test.ts so a hand-edited package.json can't
+// silently strand it.
+//
+// Why a constant and not a package.json read: the SDK runs inside edge
+// functions (Cloudflare Workers), so it must not import node:fs. A literal
+// is the only version source that works in every runtime we ship to.
+exports.SDK_VERSION = '2.4.2';

package/package.json

@@ -1,13 +1,22 @@
 {
   "name": "@myapihq/sdk",
   "license": "Apache-2.0",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "TypeScript SDK for the MyAPI ecosystem",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/myapihq/myapi.git",
+    "directory": "packages/sdk"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
-    "dev": "tsc --watch"
+    "dev": "tsc --watch",
+    "test": "cd ../cli && npx vitest run src"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",