@openhandle/sdk 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenHandle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# OpenHandle TypeScript SDK
+
+The official TypeScript and JavaScript client for the OpenHandle API.
+
+## Installation
+
+```bash
+pnpm add @openhandle/sdk
+```
+
+The package is also compatible with npm, Yarn, and Bun.
+
+## Usage
+
+Create a Test key in the [Openhandle dashboard](https://app.openhandle.dev),
+store it as `OPENHANDLE_TEST_KEY`, and create one reusable client:
+
+```ts
+import { OpenHandle } from '@openhandle/sdk';
+
+const openhandle = new OpenHandle({ apiKey: process.env.OPENHANDLE_TEST_KEY! });
+const profile = openhandle.instagram.profile('northstar_forge_test');
+
+const response = await profile.get();
+const posts = await profile.posts.list({ freshness: '24h' });
+
+console.log(response.data.handle, posts.data.length);
+```
+
+The key selects the environment. `oh_test_` keys return deterministic synthetic
+data with a `$0.000` actual charge; `oh_live_` keys use real public identifiers
+and normal billing. Never ship an API key in a browser or mobile bundle.
+
+See the [API reference](https://openhandle.dev/docs/api-reference) for a typed
+SDK example for every operation.
+
+## Resource selection
+
+The SDK follows one predictable grammar:
+
+```text
+openhandle.<platform>.<resource>(reference).<subresource>.<operation>(options)
+```
+
+Only terminal operations such as `get`, `list`, `search`, and `fetch` perform
+network requests. Selecting a resource is synchronous and reusable:
+
+```ts
+const post = openhandle.instagram.post('Db04otPRpRH');
+
+const details = await post.get();
+const comments = await post.comments.list();
+```
+
+Profile strings are usernames, including all-numeric usernames. Use an
+explicit reference for platform IDs and URLs:
+
+```ts
+openhandle.instagram.profile({ id: '25025320' });
+openhandle.instagram.profile({ url: 'https://www.instagram.com/openai/' });
+```
+
+Platform IDs are opaque strings. Numeric ID values are rejected.
+
+Use `fetch` when the URL's platform or resource is not known:
+
+```ts
+const response = await openhandle.fetch('https://www.instagram.com/p/Db04otPRpRH/', {
+    freshness: '24h',
+});
+```
+
+## Responses and billing
+
+Successful responses preserve the public envelope and add normalized request
+metadata:
+
+```ts
+const response = await openhandle.instagram.profile('northstar_forge_test').get();
+
+response.data; // Typed, camel-cased resource
+response.platform;
+response.resource;
+response.capturedAt;
+response.source;
+response.requestId;
+response.billing.cost;
+response.billing.environment;
+```
+
+Unavailable metrics are `null`, never `0`. Monetary values are decimal strings
+so applications do not lose precision.
+
+## Pagination
+
+List operations return a typed page with its opaque cursor and a lazy `next()`
+helper:
+
+```ts
+let page = await openhandle.instagram.profile('northstar_forge_test').posts.list();
+
+while (true) {
+    for (const post of page.data) {
+        console.log(post.id);
+    }
+
+    const nextPage = await page.next();
+    if (!nextPage) break;
+    page = nextPage;
+}
+```
+
+Each call to `next()` that fetches a page is one request. It returns `null`
+without a request after the final page.
+
+## Errors and retries
+
+API failures throw `OpenHandleError`. Branch on `code`, never `message`, and
+include `requestId` in logs or support requests:
+
+```ts
+import { OpenHandleError } from '@openhandle/sdk';
+
+try {
+    await openhandle.instagram.profile('quiet_harbor_test').get();
+} catch (error) {
+    if (error instanceof OpenHandleError) {
+        console.error(error.code, error.status, error.retryable, error.requestId);
+    }
+    throw error;
+}
+```
+
+The client retries explicitly retryable API failures and transient Fetch
+failures up to `maxRetries`. It honors `Retry-After` and uses capped exponential
+backoff with jitter. Reference-validation errors occur before a request and are
+available as `OpenHandleReferenceError` and `ReferenceMismatchError`.
+
+## Configuration
+
+```ts
+const openhandle = new OpenHandle({
+    apiKey: process.env.OPENHANDLE_TEST_KEY!,
+    baseUrl: 'https://api.openhandle.dev',
+    maxRetries: 2,
+    timeoutMs: 30_000,
+});
+
+await openhandle.instagram.profile('northstar_forge_test').get({
+    maxRetries: 0,
+    signal: abortController.signal,
+    timeoutMs: 10_000,
+});
+```
+
+| Option | Default | Meaning |
+|---|---:|---|
+| `apiKey` | required | Secret Test or Live API key |
+| `baseUrl` | `https://api.openhandle.dev` | API origin, useful for proxies and tests |
+| `fetch` | `globalThis.fetch` | Custom Fetch implementation |
+| `maxRetries` | `2` | Retry attempts after the initial request |
+| `timeoutMs` | `30000` | Timeout for each request attempt |
+
+`maxRetries`, `timeoutMs`, and an `AbortSignal` can also be supplied per
+operation. Per-operation values override client defaults.
+
+## Runtime support
+
+The package is ESM-only and supports Node.js 20 or newer. It also works with
+runtimes that provide the standard Fetch and AbortSignal APIs.
+
+## TypeScript conventions
+
+Request options and response fields use camel case. The exported `components`
+type represents the raw OpenAPI wire schema; terminal SDK operation return
+types apply the camel-case transformation automatically.
+
+The root package also exports camel-cased model types and named aliases for
+every operation. These are useful for wrappers, caches, callbacks, and public
+function signatures:
+
+```ts
+import type {
+    InstagramProfile,
+    InstagramProfilePostsOptions,
+    InstagramProfilePostsPage,
+    InstagramProfileResponse,
+} from '@openhandle/sdk';
+
+async function getProfile(): Promise<InstagramProfileResponse> {
+    return openhandle.instagram.profile('northstar_forge_test').get();
+}
+
+function readProfile(profile: InstagramProfile) {
+    return profile.handle;
+}
+```
+
+Operation names omit the terminal `get` or `list`: for example,
+`instagram.profile.posts.list` produces `InstagramProfilePostsOptions` and
+`InstagramProfilePostsPage`. Search terminals keep `Search` in the name when
+needed to avoid ambiguity.
+
+For example:
+
+```ts
+const result = await openhandle.instagram.profile('northstar_forge_test').posts.list({
+    freshness: '24h',
+    since: '2026-08-01T00:00:00Z',
+});
+
+result.data[0]?.publishedAt;
+```
+
+## Development
+
+The SDK is generated from the pinned OpenAPI document in
+[`openapi/openhandle.json`](./openapi/openhandle.json). The generator, runtime,
+tests, and generated output are all kept in this repository so releases are
+reproducible without access to the private OpenHandle API implementation.
+
+```bash
+pnpm install
+pnpm generate
+pnpm test
+```
+
+`pnpm generate:check` fails when the committed generated files do not match the
+pinned OpenAPI document.
+
+## Releases
+
+Conventional commits feed an automated release pull request. Merging that pull
+request creates a `v*` tag; the tag workflow tests and publishes the package to
+npm using trusted publishing. Registry credentials are not stored in GitHub.
+
+## License
+
+[MIT](./LICENSE)

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+export interface OpenHandleErrorInput {
+    cause?: unknown;
+    code: string;
+    details?: Record<string, unknown>;
+    message: string;
+    requestId?: string;
+    retryable?: boolean;
+    retryAfter?: number;
+    status?: number;
+}
+export declare class OpenHandleError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    readonly requestId?: string;
+    readonly retryable: boolean;
+    readonly retryAfter?: number;
+    readonly status?: number;
+    constructor(input: OpenHandleErrorInput);
+}
+export declare class OpenHandleReferenceError extends TypeError {
+    constructor(message: string);
+}
+export declare class ReferenceMismatchError extends OpenHandleReferenceError {
+    constructor(expectedPlatform: string, expectedResource: string, actualPlatform: string, actualResource: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,KAAK,EAAE,oBAAoB;CAU1C;AAED,qBAAa,wBAAyB,SAAQ,SAAS;gBACvC,OAAO,EAAE,MAAM;CAI9B;AAED,qBAAa,sBAAuB,SAAQ,wBAAwB;gBACpD,gBAAgB,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM;CAIjH"}

package/dist/errors.js

@@ -0,0 +1,31 @@
+export class OpenHandleError extends Error {
+    code;
+    details;
+    requestId;
+    retryable;
+    retryAfter;
+    status;
+    constructor(input) {
+        super(input.message, { cause: input.cause });
+        this.name = 'OpenHandleError';
+        this.code = input.code;
+        this.details = input.details;
+        this.requestId = input.requestId;
+        this.retryable = input.retryable ?? false;
+        this.retryAfter = input.retryAfter;
+        this.status = input.status;
+    }
+}
+export class OpenHandleReferenceError extends TypeError {
+    constructor(message) {
+        super(message);
+        this.name = 'OpenHandleReferenceError';
+    }
+}
+export class ReferenceMismatchError extends OpenHandleReferenceError {
+    constructor(expectedPlatform, expectedResource, actualPlatform, actualResource) {
+        super(`Expected a ${expectedPlatform} ${expectedResource} URL, received a ${actualPlatform} ${actualResource} URL.`);
+        this.name = 'ReferenceMismatchError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC7B,IAAI,CAAS;IACb,OAAO,CAA2B;IAClC,SAAS,CAAU;IACnB,SAAS,CAAU;IACnB,UAAU,CAAU;IACpB,MAAM,CAAU;IAEzB,YAAY,KAA2B;QACnC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC/B,CAAC;CACJ;AAED,MAAM,OAAO,wBAAyB,SAAQ,SAAS;IACnD,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IAC3C,CAAC;CACJ;AAED,MAAM,OAAO,sBAAuB,SAAQ,wBAAwB;IAChE,YAAY,gBAAwB,EAAE,gBAAwB,EAAE,cAAsB,EAAE,cAAsB;QAC1G,KAAK,CAAC,cAAc,gBAAgB,IAAI,gBAAgB,oBAAoB,cAAc,IAAI,cAAc,OAAO,CAAC,CAAC;QACrH,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACzC,CAAC;CACJ"}