@verifyapi/sdk 0.1.0

package/dist/errors.js

@@ -0,0 +1,38 @@
+/**
+ * @module @firsthandapi/sdk/errors
+ * @description SDK error types for FirstHandAPI API responses.
+ */
+/**
+ * Error thrown when FirstHandAPI returns a non-2xx response.
+ * Contains the parsed error envelope from the response body.
+ */
+export class FirstHandApiError extends Error {
+    status;
+    type;
+    requestId;
+    details;
+    constructor(status, body) {
+        super(body.message);
+        this.name = 'FirstHandApiError';
+        this.status = status;
+        this.type = body.type;
+        this.requestId = body.request_id;
+        this.details = body.details;
+    }
+    /** True if the error is retryable (429, 500, 502, 503, 504) */
+    get retryable() {
+        return this.status === 429 || this.status >= 500;
+    }
+}
+/**
+ * Error thrown when a network failure or timeout occurs.
+ */
+export class FirstHandConnectionError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = 'FirstHandConnectionError';
+        this.cause = cause;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,MAAM,CAAS;IACf,IAAI,CAAS;IACb,SAAS,CAAS;IAClB,OAAO,CAA0B;IAE1C,YAAY,MAAc,EAAE,IAAwB;QAClD,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC9B,CAAC;IAED,+DAA+D;IAC/D,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC;IACnD,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACxC,KAAK,CAAS;IAEvB,YAAY,OAAe,EAAE,KAAa;QACxC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @module @firsthandapi/sdk
+ * @description TypeScript SDK for the FirstHandAPI REST API.
+ * Typed client wrapping all v1 endpoints with auto-retry,
+ * idempotency key generation, and webhook signature verification.
+ *
+ * @example
+ * ```ts
+ * import { FirstHandClient } from '@firsthandapi/sdk';
+ *
+ * const client = new FirstHandClient({ apiKey: 'fh_live_...' });
+ * const job = await client.createJob({
+ *   job_type: 'product_photo',
+ *   title: 'Product photo for listing #1234',
+ *   instructions: 'Take a clean photo of the product on white background',
+ * });
+ * ```
+ */
+export { FirstHandClient, generateIdempotencyKey } from './client.js';
+export type { FirstHandClientOptions, ListResponse, ListOptions, GetJobOptions } from './client.js';
+export { FirstHandApiError, FirstHandConnectionError } from './errors.js';
+export type { FirstHandErrorBody, FirstHandErrorDetail } from './errors.js';
+export { verifyWebhookSignature } from './webhooks.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,sBAAsB,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC1E,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * @module @firsthandapi/sdk
+ * @description TypeScript SDK for the FirstHandAPI REST API.
+ * Typed client wrapping all v1 endpoints with auto-retry,
+ * idempotency key generation, and webhook signature verification.
+ *
+ * @example
+ * ```ts
+ * import { FirstHandClient } from '@firsthandapi/sdk';
+ *
+ * const client = new FirstHandClient({ apiKey: 'fh_live_...' });
+ * const job = await client.createJob({
+ *   job_type: 'product_photo',
+ *   title: 'Product photo for listing #1234',
+ *   instructions: 'Take a clean photo of the product on white background',
+ * });
+ * ```
+ */
+export { FirstHandClient, generateIdempotencyKey } from './client.js';
+export { FirstHandApiError, FirstHandConnectionError } from './errors.js';
+export { verifyWebhookSignature } from './webhooks.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAE1E,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC"}

package/dist/webhooks.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @module @firsthandapi/sdk/webhooks
+ * @description Webhook signature verification for FirstHandAPI webhook events.
+ * Clients use this to verify that webhook payloads were sent by FirstHandAPI.
+ *
+ * @see webhook-contract.md — Webhook signing specification
+ */
+/**
+ * Verifies a webhook signature from FirstHandAPI.
+ *
+ * @param payload - Raw request body (string or Buffer)
+ * @param signature - Value of the `X-FirstHandAPI-Signature` header
+ * @param secret - Webhook signing secret from endpoint creation
+ * @param toleranceSeconds - Maximum age of the event in seconds (default: 300 = 5 minutes)
+ * @returns true if the signature is valid
+ * @throws Error if signature is invalid, expired, or malformed
+ */
+export declare function verifyWebhookSignature(payload: string | Buffer, signature: string, secret: string, toleranceSeconds?: number): boolean;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,gBAAgB,SAAM,GACrB,OAAO,CA2CT"}

package/dist/webhooks.js

@@ -0,0 +1,52 @@
+/**
+ * @module @firsthandapi/sdk/webhooks
+ * @description Webhook signature verification for FirstHandAPI webhook events.
+ * Clients use this to verify that webhook payloads were sent by FirstHandAPI.
+ *
+ * @see webhook-contract.md — Webhook signing specification
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/**
+ * Verifies a webhook signature from FirstHandAPI.
+ *
+ * @param payload - Raw request body (string or Buffer)
+ * @param signature - Value of the `X-FirstHandAPI-Signature` header
+ * @param secret - Webhook signing secret from endpoint creation
+ * @param toleranceSeconds - Maximum age of the event in seconds (default: 300 = 5 minutes)
+ * @returns true if the signature is valid
+ * @throws Error if signature is invalid, expired, or malformed
+ */
+export function verifyWebhookSignature(payload, signature, secret, toleranceSeconds = 300) {
+    // Parse signature: "t=<timestamp>,v1=<hash>"
+    const parts = signature.split(',');
+    const timestampPart = parts.find((p) => p.startsWith('t='));
+    const hashPart = parts.find((p) => p.startsWith('v1='));
+    if (!timestampPart || !hashPart) {
+        throw new Error('Invalid webhook signature format. Expected "t=<timestamp>,v1=<hash>"');
+    }
+    const timestamp = parseInt(timestampPart.slice(2), 10);
+    const expectedHash = hashPart.slice(3);
+    if (isNaN(timestamp)) {
+        throw new Error('Invalid timestamp in webhook signature');
+    }
+    // Check tolerance
+    const now = Math.floor(Date.now() / 1000);
+    if (Math.abs(now - timestamp) > toleranceSeconds) {
+        throw new Error(`Webhook timestamp too old (${Math.abs(now - timestamp)}s, tolerance: ${toleranceSeconds}s)`);
+    }
+    // Compute expected signature
+    const body = typeof payload === 'string' ? payload : payload.toString('utf8');
+    const signedPayload = `${timestamp}.${body}`;
+    const computedHash = createHmac('sha256', secret).update(signedPayload).digest('hex');
+    // Timing-safe comparison
+    const expected = Buffer.from(expectedHash, 'hex');
+    const computed = Buffer.from(computedHash, 'hex');
+    if (expected.length !== computed.length) {
+        throw new Error('Webhook signature verification failed');
+    }
+    if (!timingSafeEqual(expected, computed)) {
+        throw new Error('Webhook signature verification failed');
+    }
+    return true;
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAwB,EACxB,SAAiB,EACjB,MAAc,EACd,gBAAgB,GAAG,GAAG;IAEtB,6CAA6C;IAC7C,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IAExD,IAAI,CAAC,aAAa,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;IAC1F,CAAC;IAED,MAAM,SAAS,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACvD,MAAM,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEvC,IAAI,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC5D,CAAC;IAED,kBAAkB;IAClB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAC1C,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,SAAS,CAAC,GAAG,gBAAgB,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CACb,8BAA8B,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,SAAS,CAAC,iBAAiB,gBAAgB,IAAI,CAC7F,CAAC;IACJ,CAAC;IAED,6BAA6B;IAC7B,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9E,MAAM,aAAa,GAAG,GAAG,SAAS,IAAI,IAAI,EAAE,CAAC;IAC7C,MAAM,YAAY,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEtF,yBAAyB;IACzB,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IAElD,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@verifyapi/sdk",
+  "version": "0.1.0",
+  "private": false,
+  "description": "TypeScript SDK for the FirstHandAPI REST API",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "test:unit": "vitest run",
+    "test:integration": "echo 'No integration tests'"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.33",
+    "@verifyapi/api-contracts": "workspace:*"
+  },
+  "keywords": [
+    "firsthandapi",
+    "human-in-the-loop",
+    "hitl",
+    "crowdsourcing",
+    "data-collection",
+    "ai",
+    "api",
+    "media-collection",
+    "verification",
+    "ugc",
+    "ground-truth",
+    "training-data",
+    "screen-recording"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.7.0"
+  }
+}