@selfxyz/enterprise-sdk 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @selfxyz/enterprise-sdk
 
-Official Node/TypeScript SDK for the [Self.xyz](https://self.xyz) Enterprise API — create verification sessions and verify webhooks with typed payloads.
+Official Node/TypeScript SDK for the [Self.xyz](https://self.xyz) Enterprise API. Create verification sessions and verify webhooks with typed payloads.
 
 > **Pre-1.0 stability**: this SDK is under active development. Minor versions may include breaking changes until `1.0.0`. Pin to an exact version in production.
 
@@ -54,7 +54,7 @@ import { SelfWebhooks } from '@selfxyz/enterprise-sdk';
 app.post('/webhooks/self', (req, res) => {
   try {
     const event = SelfWebhooks.verify(
-      req.body, // raw string or Buffer — do NOT pre-parse
+      req.body, // raw string or Buffer (do NOT pre-parse)
       req.headers, // must include the signature headers as received
       process.env.SELF_WEBHOOK_SECRET!, // whsec_... from the Self dashboard
     );
@@ -67,29 +67,132 @@ app.post('/webhooks/self', (req, res) => {
 });
 ```
 
-The raw request body must be passed exactly as received — middleware that JSON-parses the body before signature verification will cause it to fail.
+The raw request body must be passed exactly as received. Middleware that JSON-parses the body before signature verification will cause it to fail.
+
+## Proof re-verification
+
+`verifyProof` lets you independently re-verify a proof you received from Self.
+
+Persist `event.proof`, `event.proof_attributes`, and `event.environment` from the `verification.completed` payload — those three fields are everything `verifyProof` needs to re-run offline whenever you want.
+
+```ts
+import { verifyProof } from '@selfxyz/enterprise-sdk';
+
+// `verificationData` is whatever you stored when the
+// `verification.completed` webhook arrived — keep `event.proof`,
+// `event.proof_attributes`, and `event.environment` so this call
+// can run offline at any time.
+const { isValid } = await verifyProof({
+  orgId: process.env.SELF_ORG_ID!,
+  proof: verificationData.proof,
+  proofAttributes: verificationData.proof_attributes,
+  environment: verificationData.environment,
+});
+```
+
+`isValid` is true only when the Groth16 proof verifies, the minimum-age predicate is satisfied (if configured), and the user is not on an OFAC list (if OFAC checking is configured).
+
+### `orgId`
+
+`verifyProof` requires your organization UUID — it's needed to verify the proof. You can find it on the dashboard under any product's **Deploy** tab → **Re-verify proofs** step.
 
 ## Error handling
 
-The SDK throws two distinct error types:
+The SDK throws three distinct error types:
+
+- **`SelfValidationError`**: bad arguments. Raised before any network call when an SDK input (e.g. `flowId`) fails the schema check, or by `SelfWebhooks.verify` when a webhook payload doesn't match a known event shape.
+- **`SelfApiError`**: non-2xx response from the API.
+- **`WebhookVerificationError`**: invalid or missing webhook signature (re-exported from `svix`).
+
+Network-level failures (DNS errors, connection refused, request aborts) propagate as the underlying `TypeError`/`AbortError` from `fetch`. They are **not** wrapped in `SelfApiError`. Handle them separately if you need to distinguish network problems from API responses.
 
 ```ts
-import { SelfApiError, WebhookVerificationError } from '@selfxyz/enterprise-sdk';
+import {
+  SelfApiError,
+  SelfValidationError,
+  WebhookVerificationError,
+} from '@selfxyz/enterprise-sdk';
 
 try {
   await self.sessions.create({ flowId, externalUuid });
 } catch (err) {
-  if (err instanceof SelfApiError) {
-    err.statusCode; // number — HTTP status
-    err.code; // string — machine-readable error code
-    err.message; // string — human-readable
-    err.details; // Record<string, unknown> | undefined
+  if (err instanceof SelfValidationError) {
+    err.message; // 'Invalid sessions.create input: flowId (Invalid uuid)'
+    err.issues; // ZodIssue[] (raw issues for programmatic handling)
+  } else if (err instanceof SelfApiError) {
+    err.statusCode; // number (HTTP status)
+    err.code; // string (machine-readable error code; see table below)
+    err.message; // string (human-readable)
+    err.details; // Record<string, unknown> | undefined (see "When details is populated")
+    err.requestId; // string | undefined (X-Request-Id from the response)
   }
   throw err;
 }
 ```
 
-`WebhookVerificationError` is thrown by `SelfWebhooks.verify` when a signature is invalid or missing.
+### Error codes
+
+`SelfApiError.code` carries a machine-readable error code so consumers can branch on the failure mode:
+
+| Code                 | HTTP status | Meaning                                                                                                    |
+| -------------------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
+| `validation_failed`  | 400         | Request body failed server-side validation.                                                                |
+| `unauthenticated`    | 401         | Missing, invalid, or revoked API key.                                                                      |
+| `unauthenticated`    | 402         | Insufficient credits / billing gate triggered. Disambiguate from 401 via `statusCode` and check `details`. |
+| `forbidden`          | 403         | API key lacks permission for the resource.                                                                 |
+| `not_found`          | 404         | Flow or session not found.                                                                                 |
+| `conflict`           | 409         | Flow has no published version, or other state conflict.                                                    |
+| `rate_limited`       | 429         | Rate limit exceeded. Back off and retry.                                                                   |
+| `internal_error`     | 500         | Unhandled server error.                                                                                    |
+| `vendor_unavailable` | 503         | Upstream dependency is degraded (e.g. circuit breaker open).                                               |
+| `unknown_error`      | any         | API response didn't match the expected envelope. The `message` field includes a body preview.              |
+
+The set of codes may grow over time. Always include a default branch in any `switch (err.code)` so future codes don't fall through silently.
+
+```ts
+try {
+  await self.sessions.create({ flowId, externalUuid });
+} catch (err) {
+  if (!(err instanceof SelfApiError)) throw err;
+  switch (err.code) {
+    case 'rate_limited':
+      // back off and retry
+      break;
+    case 'unauthenticated':
+      if (err.statusCode === 402) {
+        // billing gate. err.details is { balance, required, planTier, creditGateMode }
+      } else {
+        // bad API key (401)
+      }
+      break;
+    case 'not_found':
+      // flow or session doesn't exist
+      break;
+    default:
+      // unknown_error or any future code. Log err.requestId and err.message
+      console.error('Self API error', { code: err.code, requestId: err.requestId });
+  }
+}
+```
+
+### When `details` is populated
+
+`SelfApiError.details` is the server's optional context object. It's set on the following errors:
+
+**`unauthenticated` + `statusCode: 402` (billing gate)**: emitted when your organization's credit balance is below what the requested verification costs:
+
+```ts
+{
+  balance: number; // spendable credits at request time
+  required: number; // credits needed for this request
+  planTier: 'free' | 'starter' | 'enterprise';
+  creditGateMode: 'hard'; // always 'hard' (soft-gate orgs do not see this error)
+}
+```
+
+**`validation_failed` + `statusCode: 400`**: `{ issues: ZodIssue[] }`. The SDK pre-validates request bodies and throws `SelfValidationError` before sending, so this server-side variant is normally caught client-side. It can surface if the SDK and server schemas fall out of sync; pin an exact SDK version in production to avoid this.
+
+For every other code, `details` is `undefined`.
 
 ## License
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { z, ZodIssue, ZodError } from 'zod';
 export { WebhookVerificationError } from 'svix';
 
 declare const verificationCompleted: z.ZodObject<{
@@ -305,6 +305,10 @@ interface SelfClientOptions {
  * });
  * console.log(session.verificationUrl);
  * ```
+ *
+ * Methods throw `SelfValidationError` for bad arguments and `SelfApiError`
+ * for non-2xx API responses. See the package README for the full error-code
+ * table.
  */
 declare class SelfClient {
     private readonly apiKey;
@@ -347,7 +351,7 @@ declare class SelfWebhooks {
      * @param secret   Webhook signing secret (`whsec_...` from the Self dashboard).
      * @returns        Parsed and verified {@link WebhookEvent}.
      * @throws         `WebhookVerificationError` if the signature is invalid.
-     * @throws         `ZodError` if the payload shape doesn't match any known event type.
+     * @throws         `SelfValidationError` if the payload shape doesn't match any known event type.
      */
     static verify(payload: string | Buffer, headers: WebhookHeaders | Record<string, string>, secret: string): WebhookEvent;
 }
@@ -357,15 +361,69 @@ interface ApiErrorBody {
     message: string;
     details?: Record<string, unknown>;
 }
+interface SelfApiErrorOptions {
+    /** Value of the `X-Request-Id` response header, if present. */
+    requestId?: string;
+}
 /**
  * Thrown when the Self API returns a non-2xx response.
  * Wraps the standard `{ error: { code, message, details? } }` envelope.
  */
 declare class SelfApiError extends Error {
+    readonly name: "SelfApiError";
     readonly statusCode: number;
     readonly code: string;
     readonly details: Record<string, unknown> | undefined;
-    constructor(statusCode: number, body: ApiErrorBody);
+    /** `X-Request-Id` from the response. Include when reporting issues to Self support. */
+    readonly requestId: string | undefined;
+    constructor(statusCode: number, body: ApiErrorBody, options?: SelfApiErrorOptions);
+}
+/**
+ * Thrown when arguments passed to the SDK (session inputs, webhook payloads)
+ * fail schema validation before the request is sent / after a webhook is
+ * verified. Wraps a `ZodError` with a human-readable message.
+ */
+declare class SelfValidationError extends Error {
+    readonly name: "SelfValidationError";
+    readonly issues: ZodIssue[];
+    constructor(zodError: ZodError, context: string);
+}
+
+interface VerifiableProofEnvelope {
+    attestationId: number;
+    proof: {
+        a: [string, string];
+        b: [[string, string], [string, string]];
+        c: [string, string];
+        curve: string;
+        protocol: 'groth16';
+    };
+    publicSignals: string[];
+    userContextData: string;
+}
+interface VerifyProofParams {
+    /** Your organization UUID — required to verify the proof. Find it on the
+     *  dashboard under any product's Deploy tab → Re-verify proofs step. */
+    orgId: string;
+    /** Raw proof envelope as received in `verification.completed.proof`. */
+    proof: VerifiableProofEnvelope;
+    /** Predicates the proof was checked against (from `verification.completed.proof_attributes`). */
+    proofAttributes: Record<string, unknown>;
+    /** From `verification.completed.environment`. Picks the right verifier endpoint constant. */
+    environment: 'test' | 'live';
 }
+interface VerifyProofResult {
+    isValid: boolean;
+}
+/**
+ * Independently re-verify a proof you received from Self.
+ *
+ * `isValid` is true iff the Groth16 proof verifies, the minimum-age
+ * predicate is satisfied (if configured), and the user is not on an OFAC
+ * list (if OFAC checking is configured).
+ *
+ * Throws an `Error` if `orgId` is missing.
+ */
+declare function verifyProof(params: VerifyProofParams): Promise<VerifyProofResult>;
 
-export { type ApiErrorBody, type CreateSessionBody, type CreateSessionInput, SelfApiError, SelfClient, type SelfClientOptions, SelfWebhooks, type CreateSessionResponse as Session, type SessionDetailResponse as SessionDetail, type VerificationCompletedPayload, type VerificationStorageCommittedPayload, type VerificationStorageFailedPayload, type WebhookEvent, type WebhookHeaders, createSessionBody, createSessionResponse, sessionDetailResponse, verificationCompleted, verificationStorageCommitted, verificationStorageFailed, webhookEvent };
+export { type ApiErrorBody, type CreateSessionBody, type CreateSessionInput, SelfApiError, SelfClient, type SelfClientOptions, SelfValidationError, SelfWebhooks, type CreateSessionResponse as Session, type SessionDetailResponse as SessionDetail, type VerifiableProofEnvelope, type VerificationCompletedPayload, type VerificationStorageCommittedPayload, type VerificationStorageFailedPayload, type VerifyProofParams, type VerifyProofResult, type WebhookEvent, type WebhookHeaders, createSessionBody, createSessionResponse, sessionDetailResponse, verificationCompleted, verificationStorageCommitted, verificationStorageFailed, verifyProof, webhookEvent };

package/dist/index.js

@@ -1,17 +1,39 @@
 // src/errors.ts
 import { WebhookVerificationError } from "svix";
 var SelfApiError = class extends Error {
+  name = "SelfApiError";
   statusCode;
   code;
   details;
-  constructor(statusCode, body) {
+  /** `X-Request-Id` from the response. Include when reporting issues to Self support. */
+  requestId;
+  constructor(statusCode, body, options) {
     super(body.message);
-    this.name = "SelfApiError";
     this.statusCode = statusCode;
     this.code = body.code;
     this.details = body.details;
+    this.requestId = options?.requestId;
   }
 };
+var SelfValidationError = class extends Error {
+  name = "SelfValidationError";
+  issues;
+  constructor(zodError, context) {
+    super(formatZodIssues(zodError.issues, context));
+    this.issues = zodError.issues;
+  }
+};
+function formatZodIssues(issues, context) {
+  if (issues.length === 0) {
+    return `Invalid ${context}`;
+  }
+  const formatted = issues.map(formatIssue).join("; ");
+  return `Invalid ${context}: ${formatted}`;
+}
+function formatIssue(issue) {
+  const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+  return `${path} (${issue.message})`;
+}
 
 // ../schemas/dist/stripe-events.js
 import { z } from "zod";
@@ -280,22 +302,39 @@ var SelfClient = class {
     }
     if (!res.ok) {
       const envelope = json;
-      throw new SelfApiError(res.status, {
-        code: envelope?.error?.code ?? "unknown_error",
-        message: envelope?.error?.message ?? (text || res.statusText),
-        ...envelope?.error?.details ? { details: envelope.error.details } : {}
-      });
+      const requestId = res.headers.get("x-request-id") ?? void 0;
+      throw new SelfApiError(
+        res.status,
+        {
+          code: envelope?.error?.code ?? "unknown_error",
+          message: envelope?.error?.message ?? fallbackMessage(text, res.statusText, json !== void 0),
+          ...envelope?.error?.details ? { details: envelope.error.details } : {}
+        },
+        requestId !== void 0 ? { requestId } : void 0
+      );
     }
     return json;
   }
   async createSession(params) {
-    createSessionBody.parse(params);
-    return this.request("POST", "/v1/sessions", params);
+    const result = createSessionBody.safeParse(params);
+    if (!result.success) {
+      throw new SelfValidationError(result.error, "sessions.create input");
+    }
+    return this.request("POST", "/v1/sessions", result.data);
   }
   getSession(id) {
     return this.request("GET", `/v1/sessions/${encodeURIComponent(id)}`);
   }
 };
+var BODY_PREVIEW_LIMIT = 200;
+function fallbackMessage(text, statusText, jsonParsed) {
+  if (text.length === 0) {
+    return `${statusText} (empty response body)`;
+  }
+  const truncated = text.length > BODY_PREVIEW_LIMIT ? `${text.slice(0, BODY_PREVIEW_LIMIT)}\u2026` : text;
+  const label = jsonParsed ? "response body" : "non-JSON response body";
+  return `${statusText} (${label}: ${JSON.stringify(truncated)})`;
+}
 
 // src/webhooks.ts
 import { z as z6 } from "zod";
@@ -314,7 +353,7 @@ var SelfWebhooks = class {
    * @param secret   Webhook signing secret (`whsec_...` from the Self dashboard).
    * @returns        Parsed and verified {@link WebhookEvent}.
    * @throws         `WebhookVerificationError` if the signature is invalid.
-   * @throws         `ZodError` if the payload shape doesn't match any known event type.
+   * @throws         `SelfValidationError` if the payload shape doesn't match any known event type.
    */
   static verify(payload, headers, secret) {
     const wh = new Webhook(secret);
@@ -322,12 +361,52 @@ var SelfWebhooks = class {
       typeof payload === "string" ? payload : payload.toString("utf-8"),
       headers
     );
-    return forwardCompatibleEvent.parse(verified);
+    const result = forwardCompatibleEvent.safeParse(verified);
+    if (!result.success) {
+      throw new SelfValidationError(result.error, "webhook payload");
+    }
+    return result.data;
   }
 };
+
+// src/verify-proof.ts
+import { AllIds, DefaultConfigStore, SelfBackendVerifier } from "@selfxyz/core";
+var VERIFIER_ENDPOINTS = {
+  live: "https://verifier.self.xyz/verify",
+  test: "https://verifier.staging.self.xyz/verify"
+};
+function orgIdToScope(orgId) {
+  return orgId.replaceAll("-", "").slice(0, 30);
+}
+async function verifyProof(params) {
+  if (!params.orgId) {
+    throw new Error("verifyProof: orgId is required");
+  }
+  const verifier = new SelfBackendVerifier(
+    orgIdToScope(params.orgId),
+    VERIFIER_ENDPOINTS[params.environment],
+    params.environment === "test",
+    AllIds,
+    new DefaultConfigStore(params.proofAttributes),
+    "uuid"
+  );
+  try {
+    const result = await verifier.verify(
+      params.proof.attestationId,
+      params.proof.proof,
+      params.proof.publicSignals,
+      params.proof.userContextData
+    );
+    const { isValid, isMinimumAgeValid, isOfacValid } = result.isValidDetails;
+    return { isValid: isValid && isMinimumAgeValid && !isOfacValid };
+  } catch {
+    return { isValid: false };
+  }
+}
 export {
   SelfApiError,
   SelfClient,
+  SelfValidationError,
   SelfWebhooks,
   WebhookVerificationError,
   createSessionBody,
@@ -336,5 +415,6 @@ export {
   verificationCompleted,
   verificationStorageCommitted,
   verificationStorageFailed,
+  verifyProof,
   webhookEvent
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@selfxyz/enterprise-sdk",
-  "version": "0.1.1",
-  "description": "Node/TS SDK for Self.xyz enterprise verification — session creation, webhook signature verification, typed payloads.",
+  "version": "0.2.0",
+  "description": "Node/TS SDK for Self.xyz enterprise verification: session creation, webhook signature verification, typed payloads.",
   "license": "BUSL-1.1",
   "homepage": "https://self.xyz",
   "repository": {
@@ -43,6 +43,7 @@
     "clean": "rm -rf dist .turbo *.tsbuildinfo"
   },
   "dependencies": {
+    "@selfxyz/core": "^1.2.0-beta.1",
     "svix": "^1.92.2",
     "zod": "^3.24.1"
   },