@astrasyncai/verification-gateway 2.4.0 → 2.4.1

package/README.md

@@ -105,35 +105,109 @@ if (result.verified && result.accessLevel !== 'none') {
 
 ### Agent Registration
 
-Register an AI agent with the KYA backend in code (the `astrasync` CLI does the same thing from a shell).
+**Use the SDK for all agent registration**, whether you're a developer firing off a one-shot CLI call or an autonomous agent self-registering on first run. The SDK handles auth-mode routing for you: signature-authenticated callers get synchronous registration; API-key-only callers get an owner-approval handshake (server-side rule, not negotiable).
+
+#### `apiEndpoint` — runtime-challenge URL
+
+`apiEndpoint` is the URL where your agent's verification-gateway SDK is mounted to receive runtime challenges from counterparties. Optional but recommended — if you omit it, your agent declares no runtime-challenge support, which is included in the verification payload and may cause some counterparties to decline access requests.
+
+#### Two registration response modes
+
+The same `register()` call returns one of two shapes depending on auth context:
+
+- **201 active** — synchronous: returned when the request is signed with a crypto keypair (`privateKey` configured) or when authenticated via email+password. Result: `{ status: 'active', agent }`.
+- **202 pending_approval** — API-key only: the SDK was authenticated with an API key but the request was not signed. The backend emails the account owner a "Sign In to Accept" link, fires a dashboard alert, and returns a tracking token. Result: `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The agent becomes active only after the owner approves.
+
+This split enforces the platform rule that **API-key registrations always require owner step-up** — registering an agent autonomously with just an API key is not a sufficient authority signal on its own.
+
+#### Pattern A — developer / long-running agent (block until approved)
+
+Best for CLI tools, dev-machine first-run, and long-running services:
 
 ```typescript
-import { AstraSync } from '@astrasyncai/verification-gateway/registration';
+import {
+  AstraSync,
+  RegistrationDeniedError,
+  RegistrationTimeoutError,
+} from '@astrasyncai/verification-gateway/registration';
 
-const astrasync = new AstraSync({
-  apiKey: process.env.ASTRASYNC_API_KEY, // or { email, password }
-  // Optional: privateKey for secp256k1 request signing
-  privateKey: process.env.ASTRASYNC_PRIVATE_KEY,
+const sdk = new AstraSync({
+  apiKey: process.env.ASTRASYNC_API_KEY,
+  privateKey: process.env.ASTRASYNC_PRIVATE_KEY, // optional — when set, 201 sync path
 });
 
-const result = await astrasync.register({
+try {
+  const agent = await sdk.register({
+    name: 'invoice-bot',
+    description: 'Reconciles AP/AR across accounting systems.',
+    agentType: 'autonomous',
+    apiEndpoint: 'https://invoice-bot.example.com', // runtime-challenge URL
+    model: { modelProvider: 'anthropic', modelName: 'claude-sonnet-4-5' },
+    framework: { frameworkName: 'langchain', frameworkVersion: '0.3.0' },
+    protocols: ['a2a', 'mcp'],
+    pdlss: {
+      purpose: {
+        categories: ['accounting'],
+        allowedActions: ['accounting.read', 'accounting.write'],
+      },
+      limits: { stepUpThreshold: 1_000, approvalThreshold: 10_000, currency: 'USD' },
+      scope: { resources: ['xero.invoices', 'quickbooks.bills'] },
+      selfInstantiation: { allowed: false },
+    },
+    // Blocking mode: poll until the request resolves.
+    waitForApproval: true,
+    timeoutMs: 10 * 60 * 1000, // 10 minutes default
+    onPending: ({ ageMs }) =>
+      console.log(`Awaiting owner approval (${(ageMs / 1000).toFixed(0)}s)…`),
+  });
+  console.log(`Agent registered: ${agent.astrasyncIdLevel1}`);
+} catch (err) {
+  if (err instanceof RegistrationDeniedError) {
+    console.error('Owner denied:', err.reason);
+  } else if (err instanceof RegistrationTimeoutError) {
+    console.error(
+      'Timed out — request is still active server-side; poll later via sdk.waitForApproval(requestId)'
+    );
+  } else {
+    throw err;
+  }
+}
+```
+
+#### Pattern B — serverless / scheduled agent (non-blocking, exit and resume)
+
+Best for Lambda / Cloud Functions / cron-driven self-registration where you can't hold the runtime open for minutes:
+
+```typescript
+const sdk = new AstraSync({ apiKey: process.env.ASTRASYNC_API_KEY });
+
+const result = await sdk.register({
   name: 'invoice-bot',
-  description: 'Reconciles AP/AR across accounting systems.',
-  agentType: 'autonomous',
-  model: { modelProvider: 'anthropic', modelName: 'claude-sonnet-4-5' },
-  framework: { frameworkName: 'langchain', frameworkVersion: '0.3.0' },
-  protocols: ['a2a', 'mcp'],
-  pdlss: {
-    purpose: { allowed: ['accounting.read', 'accounting.write'] },
-    duration: { requested: 'P30D' },
-    limits: { transactionValue: 5000, currency: 'USD' },
-    scope: { resources: ['xero.invoices', 'quickbooks.bills'] },
-    selfInstantiation: { allowed: false },
-  },
+  apiEndpoint: 'https://invoice-bot.example.com',
+  pdlss: { purpose: { categories: ['accounting'], allowedActions: ['accounting.read'] } },
 });
 
-console.log(`Agent registered: ${result.agent.astraId}`);
-console.log(`Trust score: ${result.agent.trustScore}`); // dynamic; recomputed on every verify-access call
+if (result.status === 'pending_approval') {
+  // Store the requestId in your durable storage (DynamoDB, KV, etc.)
+  await store.set('astrasync.pendingRequestId', result.requestId);
+  console.log(`Awaiting owner approval at ${result.pollUrl}; will resume on next scheduled run.`);
+  return; // function exits — owner has time to approve
+}
+
+console.log(`Agent registered as ${result.agent.astrasyncIdLevel1}`);
+```
+
+On the next scheduled run, resume by polling:
+
+```typescript
+const requestId = await store.get('astrasync.pendingRequestId');
+const status = await sdk.pollRegistration(requestId);
+if (status.state === 'approved') {
+  await store.set('astrasync.agentId', status.agent.kyaAgentId);
+  await store.delete('astrasync.pendingRequestId');
+} else if (status.state === 'denied' || status.state === 'expired') {
+  console.error(`Registration terminated: ${status.state}`);
+}
 ```
 
 CLI equivalent — same surface from a shell, also via `npx`:
@@ -143,9 +217,12 @@ npx astrasync register --name invoice-bot --agent-type autonomous \
   --model-provider anthropic --model-name claude-sonnet-4-5 \
   --framework-name langchain --framework-version 0.3.0 \
   --protocols a2a,mcp \
-  --pdlss '{"purpose":{"allowed":["accounting.read","accounting.write"]}, ...}'
+  --api-endpoint https://invoice-bot.example.com \
+  --pdlss '{"purpose":{"categories":["accounting"],"allowedActions":["accounting.read"]}}'
 ```
 
+The CLI uses the same response logic — it will print a "Sign in to approve" message and a poll URL when the response is 202 pending, and exit non-zero on deny/expire.
+
 > `/registration` is for **one-shot onboarding** — register an agent, look up its public profile, check API health. For **per-request credential injection** (attaching ASTRA-id, sessionId, PDLSS to outgoing HTTP / A2A / MCP calls from an already-registered agent), use `/agent` (`AgentClient`). The two roles are deliberately separate concerns: registration is identity, `/agent` is runtime.
 
 > A `PDLSSConfig` type exists in both `/registration` and `/agent`, with **different shapes**. `/registration`'s `PDLSSConfig` is the boundary declaration submitted at register time; `/agent`'s `PDLSSConfig` is the per-request runtime request shape. Disambiguate via the import path — the root export deliberately does not re-export either.

package/dist/bin/astrasync.js

@@ -52,9 +52,44 @@ var AuthenticationError = class extends AstraSyncError {
     this.name = "AuthenticationError";
   }
 };
+var RegistrationDeniedError = class extends AstraSyncError {
+  constructor(requestId, reason) {
+    super(
+      `Registration request ${requestId} was denied by the account owner.${reason ? ` Reason: ${reason}` : ""}`,
+      403,
+      "REGISTRATION_DENIED"
+    );
+    this.name = "RegistrationDeniedError";
+    this.requestId = requestId;
+    this.reason = reason;
+  }
+};
+var RegistrationExpiredError = class extends AstraSyncError {
+  constructor(requestId) {
+    super(
+      `Registration request ${requestId} expired before the owner approved it. Submit a new registration request.`,
+      410,
+      "REGISTRATION_EXPIRED"
+    );
+    this.name = "RegistrationExpiredError";
+    this.requestId = requestId;
+  }
+};
+var RegistrationTimeoutError = class extends AstraSyncError {
+  constructor(requestId) {
+    super(
+      `Timed out waiting for owner approval of registration request ${requestId}. The request is still active server-side; poll the request to resume waiting.`,
+      408,
+      "REGISTRATION_TIMEOUT"
+    );
+    this.name = "RegistrationTimeoutError";
+    this.requestId = requestId;
+  }
+};
 
 // src/registration/api.ts
 var DEFAULT_BASE_URL = "https://astrasync.ai";
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 var AstraSync = class {
   constructor(config = {}) {
     this.baseUrl = (config.baseUrl || process.env.ASTRASYNC_API_URL || DEFAULT_BASE_URL).replace(
@@ -76,7 +111,36 @@ var AstraSync = class {
   }
   /**
    * Register a new AI agent on the AstraSync KYA Platform.
-   * Sends full payload including model, framework, PDLSS, and metadata.
+   *
+   * The backend response depends on auth context:
+   * - **Crypto-keypair signed** (`privateKey` configured): synchronous 201,
+   *   returns `{ status: 'active', agent }`.
+   * - **API-key only** (no signature): 202 pending, returns
+   *   `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The
+   *   owner is notified by email and a dashboard alert is emitted; the agent
+   *   becomes active only after the owner approves.
+   *
+   * Blocking mode: pass `{ waitForApproval: true }` to have the SDK poll the
+   * request until it resolves, then return the live agent record. The promise
+   * rejects with `RegistrationDeniedError`, `RegistrationExpiredError`, or
+   * `RegistrationTimeoutError` on the corresponding terminal states.
+   *
+   * @example Non-blocking (default — best for serverless / scheduled agents):
+   * ```typescript
+   * const result = await sdk.register({ name, pdlss });
+   * if (result.status === 'pending_approval') {
+   *   storeRequestId(result.requestId);
+   *   return; // function exits; resume later via pollRegistration()
+   * }
+   * ```
+   *
+   * @example Blocking (best for long-running services + CLI):
+   * ```typescript
+   * const agent = await sdk.register({
+   *   name, pdlss, waitForApproval: true, timeoutMs: 600_000,
+   *   onPending: ({ ageMs }) => console.log(`waiting ${ageMs}ms`),
+   * });
+   * ```
    */
   async register(options) {
     const body = {
@@ -90,7 +154,84 @@ var AstraSync = class {
       ...options.metadata && { metadata: options.metadata },
       ...options.pdlss && { pdlss: options.pdlss }
     };
-    return this.request("POST", "/api/agents/register", body);
+    const { status, body: raw } = await this.requestWithStatus("POST", "/api/agents/register", body);
+    if (status === 201) {
+      const active = {
+        status: "active",
+        agent: raw.data.agent
+      };
+      return active;
+    }
+    const pendingBody = raw;
+    const pending = {
+      status: "pending_approval",
+      requestId: pendingBody.requestId,
+      expiresAt: pendingBody.expiresAt,
+      pollUrl: pendingBody.pollUrl,
+      message: pendingBody.message
+    };
+    if (!options.waitForApproval) return pending;
+    return this.waitForApproval(pendingBody.requestId, options);
+  }
+  /**
+   * Poll the current state of a pending-approval registration request.
+   *
+   * Useful for caller-driven polling when `waitForApproval: false` (the
+   * default). The endpoint is unauthenticated — pass the `requestId` that
+   * was returned from the 202 response.
+   *
+   * @returns `state: 'pending'` while awaiting; `'approved'` carries the
+   *          minted agent in `agent`; `'denied'` may carry the owner's
+   *          `reason`; `'expired'` is terminal after 14 days.
+   */
+  async pollRegistration(requestId) {
+    const url = `${this.baseUrl}/api/agents/request-registration/${requestId}`;
+    const res = await fetch(url, { headers: { Accept: "application/json" } });
+    if (!res.ok) {
+      const errBody = await res.json().catch(() => ({}));
+      throw new AstraSyncError(
+        errBody.error || `pollRegistration failed: ${res.status}`,
+        res.status,
+        errBody.code
+      );
+    }
+    return await res.json();
+  }
+  /**
+   * Block until a pending registration request resolves to a terminal state.
+   * Resolves to the live `AgentRecord` on approval; rejects with the matching
+   * Registration*Error on deny/expire/timeout. Usually called via
+   * `register({ waitForApproval: true })`, but exposed for callers that want
+   * to fire-and-forget the initial register call and resume waiting later
+   * (e.g. after restoring a stored `requestId` on cold start).
+   */
+  async waitForApproval(requestId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10 * 60 * 1e3;
+    const pollIntervalMs = options.pollIntervalMs ?? 5e3;
+    const start = Date.now();
+    const deadline = start + timeoutMs;
+    while (Date.now() < deadline) {
+      const result = await this.pollRegistration(requestId);
+      const ageMs = Date.now() - start;
+      options.onPending?.({ requestId, ageMs });
+      if (result.state === "approved") {
+        if (!result.agent) {
+          throw new AstraSyncError(
+            `Registration ${requestId} reported approved but no agent payload returned.`,
+            500
+          );
+        }
+        return result.agent;
+      }
+      if (result.state === "denied") {
+        throw new RegistrationDeniedError(requestId, result.reason);
+      }
+      if (result.state === "expired") {
+        throw new RegistrationExpiredError(requestId);
+      }
+      await sleep(pollIntervalMs);
+    }
+    throw new RegistrationTimeoutError(requestId);
   }
   /**
    * Look up an agent's public profile by ASTRA ID or UUID.
@@ -110,6 +251,15 @@ var AstraSync = class {
   }
   // ── Private helpers ──────────────────────────────────────────────
   async request(method, endpoint, body) {
+    const { body: parsed } = await this.requestWithStatus(method, endpoint, body);
+    return parsed;
+  }
+  /**
+   * Variant of {@link request} that also returns the HTTP status code, so
+   * callers can branch on 201 vs 202 (or other success codes) without losing
+   * type information about the response body.
+   */
+  async requestWithStatus(method, endpoint, body) {
     const url = `${this.baseUrl}${endpoint}`;
     const headers = {
       "Content-Type": "application/json"
@@ -136,7 +286,7 @@ var AstraSync = class {
         errorBody.code
       );
     }
-    return res.json();
+    return { status: res.status, body: await res.json() };
   }
   async getAuthToken() {
     if (this.apiKey) {

package/dist/registration/index.d.mts

@@ -93,6 +93,12 @@ interface RegisterOptions {
     name: string;
     description?: string;
     agentType?: string;
+    /**
+     * URL where your agent's verification-gateway SDK is mounted for runtime
+     * challenges. Optional — if omitted, your agent declares no runtime-challenge
+     * support and some counterparties may decline access requests. Mirrors the
+     * webUI "API endpoint" field.
+     */
     apiEndpoint?: string;
     model?: ModelConfig;
     framework?: FrameworkConfig;
@@ -101,7 +107,59 @@ interface RegisterOptions {
     metadata?: Record<string, unknown>;
     pdlss?: PDLSSConfig;
 }
-/** Response from agent registration. */
+/**
+ * Optional blocking-mode flags for `register()`. When `waitForApproval` is
+ * true and the backend returns 202 pending, the SDK polls until the request
+ * resolves (approved → returns Agent; denied/expired → throws; timeout →
+ * throws). The default is non-blocking: the SDK returns the pending result
+ * immediately and the caller handles polling itself.
+ */
+interface WaitForApprovalOptions {
+    /** Block until the request resolves. Default: false. */
+    waitForApproval?: boolean;
+    /** How long to wait in blocking mode. Default: 600_000ms (10 min). */
+    timeoutMs?: number;
+    /** Poll cadence in blocking mode. Default: 5000ms. */
+    pollIntervalMs?: number;
+    /** Called once per poll while still pending; useful for progress UX. */
+    onPending?: (event: {
+        requestId: string;
+        ageMs: number;
+    }) => void;
+}
+/**
+ * Discriminated registration result.
+ *
+ * - `active`: synchronous path (crypto-keypair signature verified, or
+ *   email+password auth). `agent` is the live record.
+ * - `pending_approval`: API-key auth path. The owner has been notified by
+ *   email and a dashboard alert. Poll `pollUrl` or call
+ *   `sdk.pollRegistration(requestId)` to track progress, or re-call
+ *   `register` with `waitForApproval: true` to block.
+ */
+type RegisterResult = {
+    status: 'active';
+    agent: AgentRecord;
+} | {
+    status: 'pending_approval';
+    requestId: string;
+    expiresAt: string;
+    pollUrl: string;
+    message?: string;
+};
+/**
+ * Response shape from `pollRegistration(requestId)` and the internal poll
+ * loop. State `pending` means still awaiting owner; the others are terminal.
+ */
+interface PollRegistrationResult {
+    state: 'pending' | 'approved' | 'denied' | 'expired';
+    agent?: AgentRecord;
+    reason?: string;
+}
+/**
+ * Response from agent registration (raw 201 body). Use {@link RegisterResult}
+ * for the consumer-facing shape returned from `sdk.register()`.
+ */
 interface RegistrationResponse {
     success: boolean;
     message: string;
@@ -109,6 +167,15 @@ interface RegistrationResponse {
         agent: AgentRecord;
     };
 }
+/** Raw 202 body — internal type, exposed via {@link RegisterResult}. */
+interface PendingRegistrationResponse {
+    success: true;
+    status: 'pending_approval';
+    requestId: string;
+    expiresAt: string;
+    pollUrl: string;
+    message?: string;
+}
 /** Agent record from the API. */
 interface AgentRecord {
     kyaAgentId: string;
@@ -175,9 +242,59 @@ declare class AstraSync {
     constructor(config?: AstraSyncConfig);
     /**
      * Register a new AI agent on the AstraSync KYA Platform.
-     * Sends full payload including model, framework, PDLSS, and metadata.
+     *
+     * The backend response depends on auth context:
+     * - **Crypto-keypair signed** (`privateKey` configured): synchronous 201,
+     *   returns `{ status: 'active', agent }`.
+     * - **API-key only** (no signature): 202 pending, returns
+     *   `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The
+     *   owner is notified by email and a dashboard alert is emitted; the agent
+     *   becomes active only after the owner approves.
+     *
+     * Blocking mode: pass `{ waitForApproval: true }` to have the SDK poll the
+     * request until it resolves, then return the live agent record. The promise
+     * rejects with `RegistrationDeniedError`, `RegistrationExpiredError`, or
+     * `RegistrationTimeoutError` on the corresponding terminal states.
+     *
+     * @example Non-blocking (default — best for serverless / scheduled agents):
+     * ```typescript
+     * const result = await sdk.register({ name, pdlss });
+     * if (result.status === 'pending_approval') {
+     *   storeRequestId(result.requestId);
+     *   return; // function exits; resume later via pollRegistration()
+     * }
+     * ```
+     *
+     * @example Blocking (best for long-running services + CLI):
+     * ```typescript
+     * const agent = await sdk.register({
+     *   name, pdlss, waitForApproval: true, timeoutMs: 600_000,
+     *   onPending: ({ ageMs }) => console.log(`waiting ${ageMs}ms`),
+     * });
+     * ```
      */
-    register(options: RegisterOptions): Promise<RegistrationResponse>;
+    register(options: RegisterOptions & WaitForApprovalOptions): Promise<RegisterResult | AgentRecord>;
+    /**
+     * Poll the current state of a pending-approval registration request.
+     *
+     * Useful for caller-driven polling when `waitForApproval: false` (the
+     * default). The endpoint is unauthenticated — pass the `requestId` that
+     * was returned from the 202 response.
+     *
+     * @returns `state: 'pending'` while awaiting; `'approved'` carries the
+     *          minted agent in `agent`; `'denied'` may carry the owner's
+     *          `reason`; `'expired'` is terminal after 14 days.
+     */
+    pollRegistration(requestId: string): Promise<PollRegistrationResult>;
+    /**
+     * Block until a pending registration request resolves to a terminal state.
+     * Resolves to the live `AgentRecord` on approval; rejects with the matching
+     * Registration*Error on deny/expire/timeout. Usually called via
+     * `register({ waitForApproval: true })`, but exposed for callers that want
+     * to fire-and-forget the initial register call and resume waiting later
+     * (e.g. after restoring a stored `requestId` on cold start).
+     */
+    waitForApproval(requestId: string, options?: WaitForApprovalOptions): Promise<AgentRecord>;
     /**
      * Look up an agent's public profile by ASTRA ID or UUID.
      */
@@ -187,6 +304,12 @@ declare class AstraSync {
      */
     health(): Promise<HealthResponse>;
     private request;
+    /**
+     * Variant of {@link request} that also returns the HTTP status code, so
+     * callers can branch on 201 vs 202 (or other success codes) without losing
+     * type information about the response body.
+     */
+    private requestWithStatus;
     private getAuthToken;
     /**
      * Sign a request using secp256k1 (ethers.js).
@@ -214,5 +337,33 @@ declare class KYDRequiredError extends AstraSyncError {
 declare class AuthenticationError extends AstraSyncError {
     constructor(message: string);
 }
+/**
+ * Thrown by `register({ waitForApproval: true })` when the owner denies the
+ * pending registration request. The `reason` field, when present, mirrors the
+ * deny note the owner left in the dashboard.
+ */
+declare class RegistrationDeniedError extends AstraSyncError {
+    readonly requestId: string;
+    readonly reason?: string;
+    constructor(requestId: string, reason?: string);
+}
+/**
+ * Thrown by `register({ waitForApproval: true })` when the pending request
+ * passes its 14-day TTL with no owner decision. The agent must re-submit.
+ */
+declare class RegistrationExpiredError extends AstraSyncError {
+    readonly requestId: string;
+    constructor(requestId: string);
+}
+/**
+ * Thrown by `register({ waitForApproval: true })` when the caller's local
+ * `timeoutMs` elapses before the owner makes a decision. The request is still
+ * live server-side — poll `pollRegistration(requestId)` to resume waiting, or
+ * call `waitForApproval` again with a longer timeout.
+ */
+declare class RegistrationTimeoutError extends AstraSyncError {
+    readonly requestId: string;
+    constructor(requestId: string);
+}
 
-export { type AgentProtocol, type AgentRecord, AstraSync, type AstraSyncConfig, AstraSyncError, AuthenticationError, type FrameworkConfig, type HealthResponse, KYDRequiredError, type ModelConfig, type PDLSSConfig, type PDLSSDuration, type PDLSSLimits, type PDLSSPurpose, type PDLSSScope, type PDLSSSelfInstantiation, type RegisterOptions, type RegistrationResponse, type VerifyResponse };
+export { type AgentProtocol, type AgentRecord, AstraSync, type AstraSyncConfig, AstraSyncError, AuthenticationError, type FrameworkConfig, type HealthResponse, KYDRequiredError, type ModelConfig, type PDLSSConfig, type PDLSSDuration, type PDLSSLimits, type PDLSSPurpose, type PDLSSScope, type PDLSSSelfInstantiation, type PendingRegistrationResponse, type PollRegistrationResult, type RegisterOptions, type RegisterResult, RegistrationDeniedError, RegistrationExpiredError, type RegistrationResponse, RegistrationTimeoutError, type VerifyResponse, type WaitForApprovalOptions };

package/dist/registration/index.d.ts

@@ -93,6 +93,12 @@ interface RegisterOptions {
     name: string;
     description?: string;
     agentType?: string;
+    /**
+     * URL where your agent's verification-gateway SDK is mounted for runtime
+     * challenges. Optional — if omitted, your agent declares no runtime-challenge
+     * support and some counterparties may decline access requests. Mirrors the
+     * webUI "API endpoint" field.
+     */
     apiEndpoint?: string;
     model?: ModelConfig;
     framework?: FrameworkConfig;
@@ -101,7 +107,59 @@ interface RegisterOptions {
     metadata?: Record<string, unknown>;
     pdlss?: PDLSSConfig;
 }
-/** Response from agent registration. */
+/**
+ * Optional blocking-mode flags for `register()`. When `waitForApproval` is
+ * true and the backend returns 202 pending, the SDK polls until the request
+ * resolves (approved → returns Agent; denied/expired → throws; timeout →
+ * throws). The default is non-blocking: the SDK returns the pending result
+ * immediately and the caller handles polling itself.
+ */
+interface WaitForApprovalOptions {
+    /** Block until the request resolves. Default: false. */
+    waitForApproval?: boolean;
+    /** How long to wait in blocking mode. Default: 600_000ms (10 min). */
+    timeoutMs?: number;
+    /** Poll cadence in blocking mode. Default: 5000ms. */
+    pollIntervalMs?: number;
+    /** Called once per poll while still pending; useful for progress UX. */
+    onPending?: (event: {
+        requestId: string;
+        ageMs: number;
+    }) => void;
+}
+/**
+ * Discriminated registration result.
+ *
+ * - `active`: synchronous path (crypto-keypair signature verified, or
+ *   email+password auth). `agent` is the live record.
+ * - `pending_approval`: API-key auth path. The owner has been notified by
+ *   email and a dashboard alert. Poll `pollUrl` or call
+ *   `sdk.pollRegistration(requestId)` to track progress, or re-call
+ *   `register` with `waitForApproval: true` to block.
+ */
+type RegisterResult = {
+    status: 'active';
+    agent: AgentRecord;
+} | {
+    status: 'pending_approval';
+    requestId: string;
+    expiresAt: string;
+    pollUrl: string;
+    message?: string;
+};
+/**
+ * Response shape from `pollRegistration(requestId)` and the internal poll
+ * loop. State `pending` means still awaiting owner; the others are terminal.
+ */
+interface PollRegistrationResult {
+    state: 'pending' | 'approved' | 'denied' | 'expired';
+    agent?: AgentRecord;
+    reason?: string;
+}
+/**
+ * Response from agent registration (raw 201 body). Use {@link RegisterResult}
+ * for the consumer-facing shape returned from `sdk.register()`.
+ */
 interface RegistrationResponse {
     success: boolean;
     message: string;
@@ -109,6 +167,15 @@ interface RegistrationResponse {
         agent: AgentRecord;
     };
 }
+/** Raw 202 body — internal type, exposed via {@link RegisterResult}. */
+interface PendingRegistrationResponse {
+    success: true;
+    status: 'pending_approval';
+    requestId: string;
+    expiresAt: string;
+    pollUrl: string;
+    message?: string;
+}
 /** Agent record from the API. */
 interface AgentRecord {
     kyaAgentId: string;
@@ -175,9 +242,59 @@ declare class AstraSync {
     constructor(config?: AstraSyncConfig);
     /**
      * Register a new AI agent on the AstraSync KYA Platform.
-     * Sends full payload including model, framework, PDLSS, and metadata.
+     *
+     * The backend response depends on auth context:
+     * - **Crypto-keypair signed** (`privateKey` configured): synchronous 201,
+     *   returns `{ status: 'active', agent }`.
+     * - **API-key only** (no signature): 202 pending, returns
+     *   `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The
+     *   owner is notified by email and a dashboard alert is emitted; the agent
+     *   becomes active only after the owner approves.
+     *
+     * Blocking mode: pass `{ waitForApproval: true }` to have the SDK poll the
+     * request until it resolves, then return the live agent record. The promise
+     * rejects with `RegistrationDeniedError`, `RegistrationExpiredError`, or
+     * `RegistrationTimeoutError` on the corresponding terminal states.
+     *
+     * @example Non-blocking (default — best for serverless / scheduled agents):
+     * ```typescript
+     * const result = await sdk.register({ name, pdlss });
+     * if (result.status === 'pending_approval') {
+     *   storeRequestId(result.requestId);
+     *   return; // function exits; resume later via pollRegistration()
+     * }
+     * ```
+     *
+     * @example Blocking (best for long-running services + CLI):
+     * ```typescript
+     * const agent = await sdk.register({
+     *   name, pdlss, waitForApproval: true, timeoutMs: 600_000,
+     *   onPending: ({ ageMs }) => console.log(`waiting ${ageMs}ms`),
+     * });
+     * ```
      */
-    register(options: RegisterOptions): Promise<RegistrationResponse>;
+    register(options: RegisterOptions & WaitForApprovalOptions): Promise<RegisterResult | AgentRecord>;
+    /**
+     * Poll the current state of a pending-approval registration request.
+     *
+     * Useful for caller-driven polling when `waitForApproval: false` (the
+     * default). The endpoint is unauthenticated — pass the `requestId` that
+     * was returned from the 202 response.
+     *
+     * @returns `state: 'pending'` while awaiting; `'approved'` carries the
+     *          minted agent in `agent`; `'denied'` may carry the owner's
+     *          `reason`; `'expired'` is terminal after 14 days.
+     */
+    pollRegistration(requestId: string): Promise<PollRegistrationResult>;
+    /**
+     * Block until a pending registration request resolves to a terminal state.
+     * Resolves to the live `AgentRecord` on approval; rejects with the matching
+     * Registration*Error on deny/expire/timeout. Usually called via
+     * `register({ waitForApproval: true })`, but exposed for callers that want
+     * to fire-and-forget the initial register call and resume waiting later
+     * (e.g. after restoring a stored `requestId` on cold start).
+     */
+    waitForApproval(requestId: string, options?: WaitForApprovalOptions): Promise<AgentRecord>;
     /**
      * Look up an agent's public profile by ASTRA ID or UUID.
      */
@@ -187,6 +304,12 @@ declare class AstraSync {
      */
     health(): Promise<HealthResponse>;
     private request;
+    /**
+     * Variant of {@link request} that also returns the HTTP status code, so
+     * callers can branch on 201 vs 202 (or other success codes) without losing
+     * type information about the response body.
+     */
+    private requestWithStatus;
     private getAuthToken;
     /**
      * Sign a request using secp256k1 (ethers.js).
@@ -214,5 +337,33 @@ declare class KYDRequiredError extends AstraSyncError {
 declare class AuthenticationError extends AstraSyncError {
     constructor(message: string);
 }
+/**
+ * Thrown by `register({ waitForApproval: true })` when the owner denies the
+ * pending registration request. The `reason` field, when present, mirrors the
+ * deny note the owner left in the dashboard.
+ */
+declare class RegistrationDeniedError extends AstraSyncError {
+    readonly requestId: string;
+    readonly reason?: string;
+    constructor(requestId: string, reason?: string);
+}
+/**
+ * Thrown by `register({ waitForApproval: true })` when the pending request
+ * passes its 14-day TTL with no owner decision. The agent must re-submit.
+ */
+declare class RegistrationExpiredError extends AstraSyncError {
+    readonly requestId: string;
+    constructor(requestId: string);
+}
+/**
+ * Thrown by `register({ waitForApproval: true })` when the caller's local
+ * `timeoutMs` elapses before the owner makes a decision. The request is still
+ * live server-side — poll `pollRegistration(requestId)` to resume waiting, or
+ * call `waitForApproval` again with a longer timeout.
+ */
+declare class RegistrationTimeoutError extends AstraSyncError {
+    readonly requestId: string;
+    constructor(requestId: string);
+}
 
-export { type AgentProtocol, type AgentRecord, AstraSync, type AstraSyncConfig, AstraSyncError, AuthenticationError, type FrameworkConfig, type HealthResponse, KYDRequiredError, type ModelConfig, type PDLSSConfig, type PDLSSDuration, type PDLSSLimits, type PDLSSPurpose, type PDLSSScope, type PDLSSSelfInstantiation, type RegisterOptions, type RegistrationResponse, type VerifyResponse };
+export { type AgentProtocol, type AgentRecord, AstraSync, type AstraSyncConfig, AstraSyncError, AuthenticationError, type FrameworkConfig, type HealthResponse, KYDRequiredError, type ModelConfig, type PDLSSConfig, type PDLSSDuration, type PDLSSLimits, type PDLSSPurpose, type PDLSSScope, type PDLSSSelfInstantiation, type PendingRegistrationResponse, type PollRegistrationResult, type RegisterOptions, type RegisterResult, RegistrationDeniedError, RegistrationExpiredError, type RegistrationResponse, RegistrationTimeoutError, type VerifyResponse, type WaitForApprovalOptions };

package/dist/registration/index.js

@@ -33,7 +33,10 @@ __export(registration_exports, {
   AstraSync: () => AstraSync,
   AstraSyncError: () => AstraSyncError,
   AuthenticationError: () => AuthenticationError,
-  KYDRequiredError: () => KYDRequiredError
+  KYDRequiredError: () => KYDRequiredError,
+  RegistrationDeniedError: () => RegistrationDeniedError,
+  RegistrationExpiredError: () => RegistrationExpiredError,
+  RegistrationTimeoutError: () => RegistrationTimeoutError
 });
 module.exports = __toCommonJS(registration_exports);
 
@@ -66,9 +69,44 @@ var AuthenticationError = class extends AstraSyncError {
     this.name = "AuthenticationError";
   }
 };
+var RegistrationDeniedError = class extends AstraSyncError {
+  constructor(requestId, reason) {
+    super(
+      `Registration request ${requestId} was denied by the account owner.${reason ? ` Reason: ${reason}` : ""}`,
+      403,
+      "REGISTRATION_DENIED"
+    );
+    this.name = "RegistrationDeniedError";
+    this.requestId = requestId;
+    this.reason = reason;
+  }
+};
+var RegistrationExpiredError = class extends AstraSyncError {
+  constructor(requestId) {
+    super(
+      `Registration request ${requestId} expired before the owner approved it. Submit a new registration request.`,
+      410,
+      "REGISTRATION_EXPIRED"
+    );
+    this.name = "RegistrationExpiredError";
+    this.requestId = requestId;
+  }
+};
+var RegistrationTimeoutError = class extends AstraSyncError {
+  constructor(requestId) {
+    super(
+      `Timed out waiting for owner approval of registration request ${requestId}. The request is still active server-side; poll the request to resume waiting.`,
+      408,
+      "REGISTRATION_TIMEOUT"
+    );
+    this.name = "RegistrationTimeoutError";
+    this.requestId = requestId;
+  }
+};
 
 // src/registration/api.ts
 var DEFAULT_BASE_URL = "https://astrasync.ai";
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 var AstraSync = class {
   constructor(config = {}) {
     this.baseUrl = (config.baseUrl || process.env.ASTRASYNC_API_URL || DEFAULT_BASE_URL).replace(
@@ -90,7 +128,36 @@ var AstraSync = class {
   }
   /**
    * Register a new AI agent on the AstraSync KYA Platform.
-   * Sends full payload including model, framework, PDLSS, and metadata.
+   *
+   * The backend response depends on auth context:
+   * - **Crypto-keypair signed** (`privateKey` configured): synchronous 201,
+   *   returns `{ status: 'active', agent }`.
+   * - **API-key only** (no signature): 202 pending, returns
+   *   `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The
+   *   owner is notified by email and a dashboard alert is emitted; the agent
+   *   becomes active only after the owner approves.
+   *
+   * Blocking mode: pass `{ waitForApproval: true }` to have the SDK poll the
+   * request until it resolves, then return the live agent record. The promise
+   * rejects with `RegistrationDeniedError`, `RegistrationExpiredError`, or
+   * `RegistrationTimeoutError` on the corresponding terminal states.
+   *
+   * @example Non-blocking (default — best for serverless / scheduled agents):
+   * ```typescript
+   * const result = await sdk.register({ name, pdlss });
+   * if (result.status === 'pending_approval') {
+   *   storeRequestId(result.requestId);
+   *   return; // function exits; resume later via pollRegistration()
+   * }
+   * ```
+   *
+   * @example Blocking (best for long-running services + CLI):
+   * ```typescript
+   * const agent = await sdk.register({
+   *   name, pdlss, waitForApproval: true, timeoutMs: 600_000,
+   *   onPending: ({ ageMs }) => console.log(`waiting ${ageMs}ms`),
+   * });
+   * ```
    */
   async register(options) {
     const body = {
@@ -104,7 +171,84 @@ var AstraSync = class {
       ...options.metadata && { metadata: options.metadata },
       ...options.pdlss && { pdlss: options.pdlss }
     };
-    return this.request("POST", "/api/agents/register", body);
+    const { status, body: raw } = await this.requestWithStatus("POST", "/api/agents/register", body);
+    if (status === 201) {
+      const active = {
+        status: "active",
+        agent: raw.data.agent
+      };
+      return active;
+    }
+    const pendingBody = raw;
+    const pending = {
+      status: "pending_approval",
+      requestId: pendingBody.requestId,
+      expiresAt: pendingBody.expiresAt,
+      pollUrl: pendingBody.pollUrl,
+      message: pendingBody.message
+    };
+    if (!options.waitForApproval) return pending;
+    return this.waitForApproval(pendingBody.requestId, options);
+  }
+  /**
+   * Poll the current state of a pending-approval registration request.
+   *
+   * Useful for caller-driven polling when `waitForApproval: false` (the
+   * default). The endpoint is unauthenticated — pass the `requestId` that
+   * was returned from the 202 response.
+   *
+   * @returns `state: 'pending'` while awaiting; `'approved'` carries the
+   *          minted agent in `agent`; `'denied'` may carry the owner's
+   *          `reason`; `'expired'` is terminal after 14 days.
+   */
+  async pollRegistration(requestId) {
+    const url = `${this.baseUrl}/api/agents/request-registration/${requestId}`;
+    const res = await fetch(url, { headers: { Accept: "application/json" } });
+    if (!res.ok) {
+      const errBody = await res.json().catch(() => ({}));
+      throw new AstraSyncError(
+        errBody.error || `pollRegistration failed: ${res.status}`,
+        res.status,
+        errBody.code
+      );
+    }
+    return await res.json();
+  }
+  /**
+   * Block until a pending registration request resolves to a terminal state.
+   * Resolves to the live `AgentRecord` on approval; rejects with the matching
+   * Registration*Error on deny/expire/timeout. Usually called via
+   * `register({ waitForApproval: true })`, but exposed for callers that want
+   * to fire-and-forget the initial register call and resume waiting later
+   * (e.g. after restoring a stored `requestId` on cold start).
+   */
+  async waitForApproval(requestId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10 * 60 * 1e3;
+    const pollIntervalMs = options.pollIntervalMs ?? 5e3;
+    const start = Date.now();
+    const deadline = start + timeoutMs;
+    while (Date.now() < deadline) {
+      const result = await this.pollRegistration(requestId);
+      const ageMs = Date.now() - start;
+      options.onPending?.({ requestId, ageMs });
+      if (result.state === "approved") {
+        if (!result.agent) {
+          throw new AstraSyncError(
+            `Registration ${requestId} reported approved but no agent payload returned.`,
+            500
+          );
+        }
+        return result.agent;
+      }
+      if (result.state === "denied") {
+        throw new RegistrationDeniedError(requestId, result.reason);
+      }
+      if (result.state === "expired") {
+        throw new RegistrationExpiredError(requestId);
+      }
+      await sleep(pollIntervalMs);
+    }
+    throw new RegistrationTimeoutError(requestId);
   }
   /**
    * Look up an agent's public profile by ASTRA ID or UUID.
@@ -124,6 +268,15 @@ var AstraSync = class {
   }
   // ── Private helpers ──────────────────────────────────────────────
   async request(method, endpoint, body) {
+    const { body: parsed } = await this.requestWithStatus(method, endpoint, body);
+    return parsed;
+  }
+  /**
+   * Variant of {@link request} that also returns the HTTP status code, so
+   * callers can branch on 201 vs 202 (or other success codes) without losing
+   * type information about the response body.
+   */
+  async requestWithStatus(method, endpoint, body) {
     const url = `${this.baseUrl}${endpoint}`;
     const headers = {
       "Content-Type": "application/json"
@@ -150,7 +303,7 @@ var AstraSync = class {
         errorBody.code
       );
     }
-    return res.json();
+    return { status: res.status, body: await res.json() };
   }
   async getAuthToken() {
     if (this.apiKey) {
@@ -207,6 +360,9 @@ var AstraSync = class {
   AstraSync,
   AstraSyncError,
   AuthenticationError,
-  KYDRequiredError
+  KYDRequiredError,
+  RegistrationDeniedError,
+  RegistrationExpiredError,
+  RegistrationTimeoutError
 });
 //# sourceMappingURL=index.js.map

package/dist/registration/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/registration/index.ts","../../src/registration/errors.ts","../../src/registration/api.ts"],"sourcesContent":["export { AstraSync } from './api';\nexport { AstraSyncError, KYDRequiredError, AuthenticationError } from './errors';\nexport type {\n  AstraSyncConfig,\n  RegisterOptions,\n  RegistrationResponse,\n  AgentRecord,\n  VerifyResponse,\n  HealthResponse,\n  PDLSSConfig,\n  PDLSSPurpose,\n  PDLSSDuration,\n  PDLSSLimits,\n  PDLSSScope,\n  PDLSSSelfInstantiation,\n  ModelConfig,\n  FrameworkConfig,\n  AgentProtocol,\n} from './types';\n","import type { ApiErrorResponse } from './types';\n\n/** Base error class for AstraSync SDK errors. */\nexport class AstraSyncError extends Error {\n  public readonly code?: string;\n  public readonly statusCode: number;\n\n  constructor(message: string, statusCode: number, code?: string) {\n    super(message);\n    this.name = 'AstraSyncError';\n    this.statusCode = statusCode;\n    this.code = code;\n  }\n}\n\n/** Thrown when KYD verification is required before agent registration. */\nexport class KYDRequiredError extends AstraSyncError {\n  public readonly kydUrl: string;\n  public readonly ownerNotified: boolean;\n\n  constructor(response: ApiErrorResponse) {\n    const kydUrl = response.kydUrl || 'https://astrasync.ai/developer-profile';\n    super(\n      `KYD verification required before registering agents.\\nComplete your KYD profile at: ${kydUrl}`,\n      403,\n      'KYD_REQUIRED'\n    );\n    this.name = 'KYDRequiredError';\n    this.kydUrl = kydUrl;\n    this.ownerNotified = response.ownerNotified || false;\n  }\n}\n\n/** Thrown when authentication fails. */\nexport class AuthenticationError extends AstraSyncError {\n  constructor(message: string) {\n    super(message, 401, 'AUTH_FAILED');\n    this.name = 'AuthenticationError';\n  }\n}\n","import type {\n  AstraSyncConfig,\n  RegisterOptions,\n  RegistrationResponse,\n  VerifyResponse,\n  HealthResponse,\n  ApiErrorResponse,\n} from './types';\nimport { AstraSyncError, KYDRequiredError, AuthenticationError } from './errors';\n\nconst DEFAULT_BASE_URL = 'https://astrasync.ai';\n\n/**\n * AstraSync SDK client for registering and managing AI agents.\n *\n * @example\n * ```typescript\n * const client = new AstraSync({ apiKey: 'kya_your_api_key' });\n * const result = await client.register({\n *   name: 'My Agent',\n *   model: { modelName: 'gpt-4o', modelProvider: 'openai', modelType: 'llm' },\n * });\n * ```\n *\n * For staging, pass `baseUrl: 'https://staging.astrasync.ai'`.\n */\nexport class AstraSync {\n  private readonly baseUrl: string;\n  private readonly apiKey?: string;\n  private readonly email?: string;\n  private readonly password?: string;\n  private readonly privateKey?: string;\n  private cachedJwt?: string;\n  private jwtExpiresAt?: number;\n\n  constructor(config: AstraSyncConfig = {}) {\n    this.baseUrl = (config.baseUrl || process.env.ASTRASYNC_API_URL || DEFAULT_BASE_URL).replace(\n      /\\/+$/,\n      ''\n    );\n\n    this.apiKey = config.apiKey || process.env.ASTRASYNC_API_KEY;\n    this.email = config.email;\n    this.password = config.password;\n    this.privateKey = config.privateKey;\n\n    if (!this.apiKey && !this.email) {\n      throw new AuthenticationError(\n        'Authentication required. Provide apiKey, or email+password. ' +\n          'Set ASTRASYNC_API_KEY env var or pass config to constructor.'\n      );\n    }\n\n    if (this.email && !this.password) {\n      throw new AuthenticationError('Password is required when using email authentication.');\n    }\n  }\n\n  /**\n   * Register a new AI agent on the AstraSync KYA Platform.\n   * Sends full payload including model, framework, PDLSS, and metadata.\n   */\n  async register(options: RegisterOptions): Promise<RegistrationResponse> {\n    const body: Record<string, unknown> = {\n      name: options.name,\n      ...(options.description && { description: options.description }),\n      ...(options.agentType && { agentType: options.agentType }),\n      ...(options.apiEndpoint && { apiEndpoint: options.apiEndpoint }),\n      ...(options.model && { model: options.model }),\n      ...(options.framework && { framework: options.framework }),\n      ...(options.protocols && { protocols: options.protocols }),\n      ...(options.metadata && { metadata: options.metadata }),\n      ...(options.pdlss && { pdlss: options.pdlss }),\n    };\n\n    return this.request<RegistrationResponse>('POST', '/api/agents/register', body);\n  }\n\n  /**\n   * Look up an agent's public profile by ASTRA ID or UUID.\n   */\n  async verify(agentId: string): Promise<VerifyResponse> {\n    return this.request<VerifyResponse>('GET', `/api/agents/verify/${agentId}`);\n  }\n\n  /**\n   * Check API health.\n   */\n  async health(): Promise<HealthResponse> {\n    const res = await fetch(`${this.baseUrl}/api/health/`);\n    if (!res.ok) {\n      throw new AstraSyncError(`Health check failed: ${res.status}`, res.status);\n    }\n    return res.json() as Promise<HealthResponse>;\n  }\n\n  // ── Private helpers ──────────────────────────────────────────────\n\n  private async request<T>(method: string, endpoint: string, body?: unknown): Promise<T> {\n    const url = `${this.baseUrl}${endpoint}`;\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n    };\n\n    // Set auth header\n    const token = await this.getAuthToken();\n    headers['Authorization'] = `Bearer ${token}`;\n\n    // Sign request if private key is configured\n    if (this.privateKey) {\n      const signature = await this.signRequest(method, endpoint, body || {});\n      headers['X-AstraSync-Signature'] = signature;\n    }\n\n    const res = await fetch(url, {\n      method,\n      headers,\n      ...(body ? { body: JSON.stringify(body) } : {}),\n    });\n\n    if (!res.ok) {\n      const errorBody = (await res\n        .json()\n        .catch(() => ({ error: res.statusText }))) as ApiErrorResponse;\n\n      // Handle KYD_REQUIRED specifically\n      if (res.status === 403 && errorBody.code === 'KYD_REQUIRED') {\n        throw new KYDRequiredError(errorBody);\n      }\n\n      throw new AstraSyncError(\n        errorBody.error || `Request failed: ${res.status}`,\n        res.status,\n        errorBody.code\n      );\n    }\n\n    return res.json() as Promise<T>;\n  }\n\n  private async getAuthToken(): Promise<string> {\n    // API key auth — use directly\n    if (this.apiKey) {\n      return this.apiKey;\n    }\n\n    // Email+password — login and cache JWT\n    if (this.cachedJwt && this.jwtExpiresAt && Date.now() < this.jwtExpiresAt) {\n      return this.cachedJwt;\n    }\n\n    const res = await fetch(`${this.baseUrl}/api/auth/login`, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ email: this.email, password: this.password }),\n    });\n\n    if (!res.ok) {\n      const errorBody = (await res.json().catch(() => ({}))) as Record<string, unknown>;\n      throw new AuthenticationError(\n        (errorBody.message as string) || (errorBody.error as string) || 'Login failed'\n      );\n    }\n\n    const data = (await res.json()) as { data: { token: string } };\n    this.cachedJwt = data.data.token;\n    // Cache for 6 days (tokens expire in 7)\n    this.jwtExpiresAt = Date.now() + 6 * 24 * 60 * 60 * 1000;\n\n    return this.cachedJwt;\n  }\n\n  /**\n   * Sign a request using secp256k1 (ethers.js).\n   * Canonical message format: METHOD:ENDPOINT:SORTED_JSON_BODY\n   * Must match apps/backend/src/services/signature-verify.service.ts exactly.\n   */\n  private async signRequest(method: string, endpoint: string, body: unknown): Promise<string> {\n    const { Wallet } = await import('ethers');\n    const sorted = this.sortObjectKeys(body);\n    const canonical = `${method}:${endpoint}:${JSON.stringify(sorted)}`;\n    const wallet = new Wallet(this.privateKey!);\n    return wallet.signMessage(canonical);\n  }\n\n  /** Recursively sort object keys for canonical JSON representation. */\n  private sortObjectKeys(obj: unknown): unknown {\n    if (obj === null || typeof obj !== 'object') {\n      return obj;\n    }\n    if (Array.isArray(obj)) {\n      return obj.map((item) => this.sortObjectKeys(item));\n    }\n    const sorted: Record<string, unknown> = {};\n    for (const key of Object.keys(obj).sort()) {\n      sorted[key] = this.sortObjectKeys((obj as Record<string, unknown>)[key]);\n    }\n    return sorted;\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/registration/index.ts","../../src/registration/errors.ts","../../src/registration/api.ts"],"sourcesContent":["export { AstraSync } from './api';\nexport {\n  AstraSyncError,\n  KYDRequiredError,\n  AuthenticationError,\n  RegistrationDeniedError,\n  RegistrationExpiredError,\n  RegistrationTimeoutError,\n} from './errors';\nexport type {\n  AstraSyncConfig,\n  RegisterOptions,\n  RegisterResult,\n  WaitForApprovalOptions,\n  PendingRegistrationResponse,\n  PollRegistrationResult,\n  RegistrationResponse,\n  AgentRecord,\n  VerifyResponse,\n  HealthResponse,\n  PDLSSConfig,\n  PDLSSPurpose,\n  PDLSSDuration,\n  PDLSSLimits,\n  PDLSSScope,\n  PDLSSSelfInstantiation,\n  ModelConfig,\n  FrameworkConfig,\n  AgentProtocol,\n} from './types';\n","import type { ApiErrorResponse } from './types';\n\n/** Base error class for AstraSync SDK errors. */\nexport class AstraSyncError extends Error {\n  public readonly code?: string;\n  public readonly statusCode: number;\n\n  constructor(message: string, statusCode: number, code?: string) {\n    super(message);\n    this.name = 'AstraSyncError';\n    this.statusCode = statusCode;\n    this.code = code;\n  }\n}\n\n/** Thrown when KYD verification is required before agent registration. */\nexport class KYDRequiredError extends AstraSyncError {\n  public readonly kydUrl: string;\n  public readonly ownerNotified: boolean;\n\n  constructor(response: ApiErrorResponse) {\n    const kydUrl = response.kydUrl || 'https://astrasync.ai/developer-profile';\n    super(\n      `KYD verification required before registering agents.\\nComplete your KYD profile at: ${kydUrl}`,\n      403,\n      'KYD_REQUIRED'\n    );\n    this.name = 'KYDRequiredError';\n    this.kydUrl = kydUrl;\n    this.ownerNotified = response.ownerNotified || false;\n  }\n}\n\n/** Thrown when authentication fails. */\nexport class AuthenticationError extends AstraSyncError {\n  constructor(message: string) {\n    super(message, 401, 'AUTH_FAILED');\n    this.name = 'AuthenticationError';\n  }\n}\n\n/**\n * Thrown by `register({ waitForApproval: true })` when the owner denies the\n * pending registration request. The `reason` field, when present, mirrors the\n * deny note the owner left in the dashboard.\n */\nexport class RegistrationDeniedError extends AstraSyncError {\n  public readonly requestId: string;\n  public readonly reason?: string;\n\n  constructor(requestId: string, reason?: string) {\n    super(\n      `Registration request ${requestId} was denied by the account owner.${reason ? ` Reason: ${reason}` : ''}`,\n      403,\n      'REGISTRATION_DENIED'\n    );\n    this.name = 'RegistrationDeniedError';\n    this.requestId = requestId;\n    this.reason = reason;\n  }\n}\n\n/**\n * Thrown by `register({ waitForApproval: true })` when the pending request\n * passes its 14-day TTL with no owner decision. The agent must re-submit.\n */\nexport class RegistrationExpiredError extends AstraSyncError {\n  public readonly requestId: string;\n\n  constructor(requestId: string) {\n    super(\n      `Registration request ${requestId} expired before the owner approved it. Submit a new registration request.`,\n      410,\n      'REGISTRATION_EXPIRED'\n    );\n    this.name = 'RegistrationExpiredError';\n    this.requestId = requestId;\n  }\n}\n\n/**\n * Thrown by `register({ waitForApproval: true })` when the caller's local\n * `timeoutMs` elapses before the owner makes a decision. The request is still\n * live server-side — poll `pollRegistration(requestId)` to resume waiting, or\n * call `waitForApproval` again with a longer timeout.\n */\nexport class RegistrationTimeoutError extends AstraSyncError {\n  public readonly requestId: string;\n\n  constructor(requestId: string) {\n    super(\n      `Timed out waiting for owner approval of registration request ${requestId}. The request is still active server-side; poll the request to resume waiting.`,\n      408,\n      'REGISTRATION_TIMEOUT'\n    );\n    this.name = 'RegistrationTimeoutError';\n    this.requestId = requestId;\n  }\n}\n","import type {\n  AstraSyncConfig,\n  RegisterOptions,\n  RegisterResult,\n  WaitForApprovalOptions,\n  PendingRegistrationResponse,\n  PollRegistrationResult,\n  RegistrationResponse,\n  VerifyResponse,\n  HealthResponse,\n  ApiErrorResponse,\n  AgentRecord,\n} from './types';\nimport {\n  AstraSyncError,\n  KYDRequiredError,\n  AuthenticationError,\n  RegistrationDeniedError,\n  RegistrationExpiredError,\n  RegistrationTimeoutError,\n} from './errors';\n\nconst DEFAULT_BASE_URL = 'https://astrasync.ai';\n\nconst sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));\n\n/**\n * AstraSync SDK client for registering and managing AI agents.\n *\n * @example\n * ```typescript\n * const client = new AstraSync({ apiKey: 'kya_your_api_key' });\n * const result = await client.register({\n *   name: 'My Agent',\n *   model: { modelName: 'gpt-4o', modelProvider: 'openai', modelType: 'llm' },\n * });\n * ```\n *\n * For staging, pass `baseUrl: 'https://staging.astrasync.ai'`.\n */\nexport class AstraSync {\n  private readonly baseUrl: string;\n  private readonly apiKey?: string;\n  private readonly email?: string;\n  private readonly password?: string;\n  private readonly privateKey?: string;\n  private cachedJwt?: string;\n  private jwtExpiresAt?: number;\n\n  constructor(config: AstraSyncConfig = {}) {\n    this.baseUrl = (config.baseUrl || process.env.ASTRASYNC_API_URL || DEFAULT_BASE_URL).replace(\n      /\\/+$/,\n      ''\n    );\n\n    this.apiKey = config.apiKey || process.env.ASTRASYNC_API_KEY;\n    this.email = config.email;\n    this.password = config.password;\n    this.privateKey = config.privateKey;\n\n    if (!this.apiKey && !this.email) {\n      throw new AuthenticationError(\n        'Authentication required. Provide apiKey, or email+password. ' +\n          'Set ASTRASYNC_API_KEY env var or pass config to constructor.'\n      );\n    }\n\n    if (this.email && !this.password) {\n      throw new AuthenticationError('Password is required when using email authentication.');\n    }\n  }\n\n  /**\n   * Register a new AI agent on the AstraSync KYA Platform.\n   *\n   * The backend response depends on auth context:\n   * - **Crypto-keypair signed** (`privateKey` configured): synchronous 201,\n   *   returns `{ status: 'active', agent }`.\n   * - **API-key only** (no signature): 202 pending, returns\n   *   `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The\n   *   owner is notified by email and a dashboard alert is emitted; the agent\n   *   becomes active only after the owner approves.\n   *\n   * Blocking mode: pass `{ waitForApproval: true }` to have the SDK poll the\n   * request until it resolves, then return the live agent record. The promise\n   * rejects with `RegistrationDeniedError`, `RegistrationExpiredError`, or\n   * `RegistrationTimeoutError` on the corresponding terminal states.\n   *\n   * @example Non-blocking (default — best for serverless / scheduled agents):\n   * ```typescript\n   * const result = await sdk.register({ name, pdlss });\n   * if (result.status === 'pending_approval') {\n   *   storeRequestId(result.requestId);\n   *   return; // function exits; resume later via pollRegistration()\n   * }\n   * ```\n   *\n   * @example Blocking (best for long-running services + CLI):\n   * ```typescript\n   * const agent = await sdk.register({\n   *   name, pdlss, waitForApproval: true, timeoutMs: 600_000,\n   *   onPending: ({ ageMs }) => console.log(`waiting ${ageMs}ms`),\n   * });\n   * ```\n   */\n  async register(\n    options: RegisterOptions & WaitForApprovalOptions\n  ): Promise<RegisterResult | AgentRecord> {\n    const body: Record<string, unknown> = {\n      name: options.name,\n      ...(options.description && { description: options.description }),\n      ...(options.agentType && { agentType: options.agentType }),\n      ...(options.apiEndpoint && { apiEndpoint: options.apiEndpoint }),\n      ...(options.model && { model: options.model }),\n      ...(options.framework && { framework: options.framework }),\n      ...(options.protocols && { protocols: options.protocols }),\n      ...(options.metadata && { metadata: options.metadata }),\n      ...(options.pdlss && { pdlss: options.pdlss }),\n    };\n\n    const { status, body: raw } = await this.requestWithStatus<\n      RegistrationResponse | PendingRegistrationResponse\n    >('POST', '/api/agents/register', body);\n\n    if (status === 201) {\n      const active: RegisterResult = {\n        status: 'active',\n        agent: (raw as RegistrationResponse).data.agent,\n      };\n      return active;\n    }\n\n    // 202 Accepted — owner approval required.\n    const pendingBody = raw as PendingRegistrationResponse;\n    const pending: RegisterResult = {\n      status: 'pending_approval',\n      requestId: pendingBody.requestId,\n      expiresAt: pendingBody.expiresAt,\n      pollUrl: pendingBody.pollUrl,\n      message: pendingBody.message,\n    };\n\n    if (!options.waitForApproval) return pending;\n\n    return this.waitForApproval(pendingBody.requestId, options);\n  }\n\n  /**\n   * Poll the current state of a pending-approval registration request.\n   *\n   * Useful for caller-driven polling when `waitForApproval: false` (the\n   * default). The endpoint is unauthenticated — pass the `requestId` that\n   * was returned from the 202 response.\n   *\n   * @returns `state: 'pending'` while awaiting; `'approved'` carries the\n   *          minted agent in `agent`; `'denied'` may carry the owner's\n   *          `reason`; `'expired'` is terminal after 14 days.\n   */\n  async pollRegistration(requestId: string): Promise<PollRegistrationResult> {\n    const url = `${this.baseUrl}/api/agents/request-registration/${requestId}`;\n    const res = await fetch(url, { headers: { Accept: 'application/json' } });\n    if (!res.ok) {\n      const errBody = (await res.json().catch(() => ({}))) as ApiErrorResponse;\n      throw new AstraSyncError(\n        errBody.error || `pollRegistration failed: ${res.status}`,\n        res.status,\n        errBody.code\n      );\n    }\n    return (await res.json()) as PollRegistrationResult;\n  }\n\n  /**\n   * Block until a pending registration request resolves to a terminal state.\n   * Resolves to the live `AgentRecord` on approval; rejects with the matching\n   * Registration*Error on deny/expire/timeout. Usually called via\n   * `register({ waitForApproval: true })`, but exposed for callers that want\n   * to fire-and-forget the initial register call and resume waiting later\n   * (e.g. after restoring a stored `requestId` on cold start).\n   */\n  async waitForApproval(\n    requestId: string,\n    options: WaitForApprovalOptions = {}\n  ): Promise<AgentRecord> {\n    const timeoutMs = options.timeoutMs ?? 10 * 60 * 1000;\n    const pollIntervalMs = options.pollIntervalMs ?? 5_000;\n    const start = Date.now();\n    const deadline = start + timeoutMs;\n\n    while (Date.now() < deadline) {\n      const result = await this.pollRegistration(requestId);\n      const ageMs = Date.now() - start;\n      options.onPending?.({ requestId, ageMs });\n\n      if (result.state === 'approved') {\n        if (!result.agent) {\n          throw new AstraSyncError(\n            `Registration ${requestId} reported approved but no agent payload returned.`,\n            500\n          );\n        }\n        return result.agent;\n      }\n      if (result.state === 'denied') {\n        throw new RegistrationDeniedError(requestId, result.reason);\n      }\n      if (result.state === 'expired') {\n        throw new RegistrationExpiredError(requestId);\n      }\n      await sleep(pollIntervalMs);\n    }\n    throw new RegistrationTimeoutError(requestId);\n  }\n\n  /**\n   * Look up an agent's public profile by ASTRA ID or UUID.\n   */\n  async verify(agentId: string): Promise<VerifyResponse> {\n    return this.request<VerifyResponse>('GET', `/api/agents/verify/${agentId}`);\n  }\n\n  /**\n   * Check API health.\n   */\n  async health(): Promise<HealthResponse> {\n    const res = await fetch(`${this.baseUrl}/api/health/`);\n    if (!res.ok) {\n      throw new AstraSyncError(`Health check failed: ${res.status}`, res.status);\n    }\n    return res.json() as Promise<HealthResponse>;\n  }\n\n  // ── Private helpers ──────────────────────────────────────────────\n\n  private async request<T>(method: string, endpoint: string, body?: unknown): Promise<T> {\n    const { body: parsed } = await this.requestWithStatus<T>(method, endpoint, body);\n    return parsed;\n  }\n\n  /**\n   * Variant of {@link request} that also returns the HTTP status code, so\n   * callers can branch on 201 vs 202 (or other success codes) without losing\n   * type information about the response body.\n   */\n  private async requestWithStatus<T>(\n    method: string,\n    endpoint: string,\n    body?: unknown\n  ): Promise<{ status: number; body: T }> {\n    const url = `${this.baseUrl}${endpoint}`;\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n    };\n\n    // Set auth header\n    const token = await this.getAuthToken();\n    headers['Authorization'] = `Bearer ${token}`;\n\n    // Sign request if private key is configured\n    if (this.privateKey) {\n      const signature = await this.signRequest(method, endpoint, body || {});\n      headers['X-AstraSync-Signature'] = signature;\n    }\n\n    const res = await fetch(url, {\n      method,\n      headers,\n      ...(body ? { body: JSON.stringify(body) } : {}),\n    });\n\n    if (!res.ok) {\n      const errorBody = (await res\n        .json()\n        .catch(() => ({ error: res.statusText }))) as ApiErrorResponse;\n\n      // Handle KYD_REQUIRED specifically\n      if (res.status === 403 && errorBody.code === 'KYD_REQUIRED') {\n        throw new KYDRequiredError(errorBody);\n      }\n\n      throw new AstraSyncError(\n        errorBody.error || `Request failed: ${res.status}`,\n        res.status,\n        errorBody.code\n      );\n    }\n\n    return { status: res.status, body: (await res.json()) as T };\n  }\n\n  private async getAuthToken(): Promise<string> {\n    // API key auth — use directly\n    if (this.apiKey) {\n      return this.apiKey;\n    }\n\n    // Email+password — login and cache JWT\n    if (this.cachedJwt && this.jwtExpiresAt && Date.now() < this.jwtExpiresAt) {\n      return this.cachedJwt;\n    }\n\n    const res = await fetch(`${this.baseUrl}/api/auth/login`, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ email: this.email, password: this.password }),\n    });\n\n    if (!res.ok) {\n      const errorBody = (await res.json().catch(() => ({}))) as Record<string, unknown>;\n      throw new AuthenticationError(\n        (errorBody.message as string) || (errorBody.error as string) || 'Login failed'\n      );\n    }\n\n    const data = (await res.json()) as { data: { token: string } };\n    this.cachedJwt = data.data.token;\n    // Cache for 6 days (tokens expire in 7)\n    this.jwtExpiresAt = Date.now() + 6 * 24 * 60 * 60 * 1000;\n\n    return this.cachedJwt;\n  }\n\n  /**\n   * Sign a request using secp256k1 (ethers.js).\n   * Canonical message format: METHOD:ENDPOINT:SORTED_JSON_BODY\n   * Must match apps/backend/src/services/signature-verify.service.ts exactly.\n   */\n  private async signRequest(method: string, endpoint: string, body: unknown): Promise<string> {\n    const { Wallet } = await import('ethers');\n    const sorted = this.sortObjectKeys(body);\n    const canonical = `${method}:${endpoint}:${JSON.stringify(sorted)}`;\n    const wallet = new Wallet(this.privateKey!);\n    return wallet.signMessage(canonical);\n  }\n\n  /** Recursively sort object keys for canonical JSON representation. */\n  private sortObjectKeys(obj: unknown): unknown {\n    if (obj === null || typeof obj !== 'object') {\n      return obj;\n    }\n    if (Array.isArray(obj)) {\n      return obj.map((item) => this.sortObjectKeys(item));\n    }\n    const sorted: Record<string, unknown> = {};\n    for (const key of Object.keys(obj).sort()) {\n      sorted[key] = this.sortObjectKeys((obj as Record<string, unknown>)[key]);\n    }\n    return sorted;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/registration/index.mjs

@@ -27,9 +27,44 @@ var AuthenticationError = class extends AstraSyncError {
     this.name = "AuthenticationError";
   }
 };
+var RegistrationDeniedError = class extends AstraSyncError {
+  constructor(requestId, reason) {
+    super(
+      `Registration request ${requestId} was denied by the account owner.${reason ? ` Reason: ${reason}` : ""}`,
+      403,
+      "REGISTRATION_DENIED"
+    );
+    this.name = "RegistrationDeniedError";
+    this.requestId = requestId;
+    this.reason = reason;
+  }
+};
+var RegistrationExpiredError = class extends AstraSyncError {
+  constructor(requestId) {
+    super(
+      `Registration request ${requestId} expired before the owner approved it. Submit a new registration request.`,
+      410,
+      "REGISTRATION_EXPIRED"
+    );
+    this.name = "RegistrationExpiredError";
+    this.requestId = requestId;
+  }
+};
+var RegistrationTimeoutError = class extends AstraSyncError {
+  constructor(requestId) {
+    super(
+      `Timed out waiting for owner approval of registration request ${requestId}. The request is still active server-side; poll the request to resume waiting.`,
+      408,
+      "REGISTRATION_TIMEOUT"
+    );
+    this.name = "RegistrationTimeoutError";
+    this.requestId = requestId;
+  }
+};
 
 // src/registration/api.ts
 var DEFAULT_BASE_URL = "https://astrasync.ai";
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 var AstraSync = class {
   constructor(config = {}) {
     this.baseUrl = (config.baseUrl || process.env.ASTRASYNC_API_URL || DEFAULT_BASE_URL).replace(
@@ -51,7 +86,36 @@ var AstraSync = class {
   }
   /**
    * Register a new AI agent on the AstraSync KYA Platform.
-   * Sends full payload including model, framework, PDLSS, and metadata.
+   *
+   * The backend response depends on auth context:
+   * - **Crypto-keypair signed** (`privateKey` configured): synchronous 201,
+   *   returns `{ status: 'active', agent }`.
+   * - **API-key only** (no signature): 202 pending, returns
+   *   `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The
+   *   owner is notified by email and a dashboard alert is emitted; the agent
+   *   becomes active only after the owner approves.
+   *
+   * Blocking mode: pass `{ waitForApproval: true }` to have the SDK poll the
+   * request until it resolves, then return the live agent record. The promise
+   * rejects with `RegistrationDeniedError`, `RegistrationExpiredError`, or
+   * `RegistrationTimeoutError` on the corresponding terminal states.
+   *
+   * @example Non-blocking (default — best for serverless / scheduled agents):
+   * ```typescript
+   * const result = await sdk.register({ name, pdlss });
+   * if (result.status === 'pending_approval') {
+   *   storeRequestId(result.requestId);
+   *   return; // function exits; resume later via pollRegistration()
+   * }
+   * ```
+   *
+   * @example Blocking (best for long-running services + CLI):
+   * ```typescript
+   * const agent = await sdk.register({
+   *   name, pdlss, waitForApproval: true, timeoutMs: 600_000,
+   *   onPending: ({ ageMs }) => console.log(`waiting ${ageMs}ms`),
+   * });
+   * ```
    */
   async register(options) {
     const body = {
@@ -65,7 +129,84 @@ var AstraSync = class {
       ...options.metadata && { metadata: options.metadata },
       ...options.pdlss && { pdlss: options.pdlss }
     };
-    return this.request("POST", "/api/agents/register", body);
+    const { status, body: raw } = await this.requestWithStatus("POST", "/api/agents/register", body);
+    if (status === 201) {
+      const active = {
+        status: "active",
+        agent: raw.data.agent
+      };
+      return active;
+    }
+    const pendingBody = raw;
+    const pending = {
+      status: "pending_approval",
+      requestId: pendingBody.requestId,
+      expiresAt: pendingBody.expiresAt,
+      pollUrl: pendingBody.pollUrl,
+      message: pendingBody.message
+    };
+    if (!options.waitForApproval) return pending;
+    return this.waitForApproval(pendingBody.requestId, options);
+  }
+  /**
+   * Poll the current state of a pending-approval registration request.
+   *
+   * Useful for caller-driven polling when `waitForApproval: false` (the
+   * default). The endpoint is unauthenticated — pass the `requestId` that
+   * was returned from the 202 response.
+   *
+   * @returns `state: 'pending'` while awaiting; `'approved'` carries the
+   *          minted agent in `agent`; `'denied'` may carry the owner's
+   *          `reason`; `'expired'` is terminal after 14 days.
+   */
+  async pollRegistration(requestId) {
+    const url = `${this.baseUrl}/api/agents/request-registration/${requestId}`;
+    const res = await fetch(url, { headers: { Accept: "application/json" } });
+    if (!res.ok) {
+      const errBody = await res.json().catch(() => ({}));
+      throw new AstraSyncError(
+        errBody.error || `pollRegistration failed: ${res.status}`,
+        res.status,
+        errBody.code
+      );
+    }
+    return await res.json();
+  }
+  /**
+   * Block until a pending registration request resolves to a terminal state.
+   * Resolves to the live `AgentRecord` on approval; rejects with the matching
+   * Registration*Error on deny/expire/timeout. Usually called via
+   * `register({ waitForApproval: true })`, but exposed for callers that want
+   * to fire-and-forget the initial register call and resume waiting later
+   * (e.g. after restoring a stored `requestId` on cold start).
+   */
+  async waitForApproval(requestId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10 * 60 * 1e3;
+    const pollIntervalMs = options.pollIntervalMs ?? 5e3;
+    const start = Date.now();
+    const deadline = start + timeoutMs;
+    while (Date.now() < deadline) {
+      const result = await this.pollRegistration(requestId);
+      const ageMs = Date.now() - start;
+      options.onPending?.({ requestId, ageMs });
+      if (result.state === "approved") {
+        if (!result.agent) {
+          throw new AstraSyncError(
+            `Registration ${requestId} reported approved but no agent payload returned.`,
+            500
+          );
+        }
+        return result.agent;
+      }
+      if (result.state === "denied") {
+        throw new RegistrationDeniedError(requestId, result.reason);
+      }
+      if (result.state === "expired") {
+        throw new RegistrationExpiredError(requestId);
+      }
+      await sleep(pollIntervalMs);
+    }
+    throw new RegistrationTimeoutError(requestId);
   }
   /**
    * Look up an agent's public profile by ASTRA ID or UUID.
@@ -85,6 +226,15 @@ var AstraSync = class {
   }
   // ── Private helpers ──────────────────────────────────────────────
   async request(method, endpoint, body) {
+    const { body: parsed } = await this.requestWithStatus(method, endpoint, body);
+    return parsed;
+  }
+  /**
+   * Variant of {@link request} that also returns the HTTP status code, so
+   * callers can branch on 201 vs 202 (or other success codes) without losing
+   * type information about the response body.
+   */
+  async requestWithStatus(method, endpoint, body) {
     const url = `${this.baseUrl}${endpoint}`;
     const headers = {
       "Content-Type": "application/json"
@@ -111,7 +261,7 @@ var AstraSync = class {
         errorBody.code
       );
     }
-    return res.json();
+    return { status: res.status, body: await res.json() };
   }
   async getAuthToken() {
     if (this.apiKey) {
@@ -167,6 +317,9 @@ export {
   AstraSync,
   AstraSyncError,
   AuthenticationError,
-  KYDRequiredError
+  KYDRequiredError,
+  RegistrationDeniedError,
+  RegistrationExpiredError,
+  RegistrationTimeoutError
 };
 //# sourceMappingURL=index.mjs.map

package/dist/registration/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/registration/errors.ts","../../src/registration/api.ts"],"sourcesContent":["import type { ApiErrorResponse } from './types';\n\n/** Base error class for AstraSync SDK errors. */\nexport class AstraSyncError extends Error {\n  public readonly code?: string;\n  public readonly statusCode: number;\n\n  constructor(message: string, statusCode: number, code?: string) {\n    super(message);\n    this.name = 'AstraSyncError';\n    this.statusCode = statusCode;\n    this.code = code;\n  }\n}\n\n/** Thrown when KYD verification is required before agent registration. */\nexport class KYDRequiredError extends AstraSyncError {\n  public readonly kydUrl: string;\n  public readonly ownerNotified: boolean;\n\n  constructor(response: ApiErrorResponse) {\n    const kydUrl = response.kydUrl || 'https://astrasync.ai/developer-profile';\n    super(\n      `KYD verification required before registering agents.\\nComplete your KYD profile at: ${kydUrl}`,\n      403,\n      'KYD_REQUIRED'\n    );\n    this.name = 'KYDRequiredError';\n    this.kydUrl = kydUrl;\n    this.ownerNotified = response.ownerNotified || false;\n  }\n}\n\n/** Thrown when authentication fails. */\nexport class AuthenticationError extends AstraSyncError {\n  constructor(message: string) {\n    super(message, 401, 'AUTH_FAILED');\n    this.name = 'AuthenticationError';\n  }\n}\n","import type {\n  AstraSyncConfig,\n  RegisterOptions,\n  RegistrationResponse,\n  VerifyResponse,\n  HealthResponse,\n  ApiErrorResponse,\n} from './types';\nimport { AstraSyncError, KYDRequiredError, AuthenticationError } from './errors';\n\nconst DEFAULT_BASE_URL = 'https://astrasync.ai';\n\n/**\n * AstraSync SDK client for registering and managing AI agents.\n *\n * @example\n * ```typescript\n * const client = new AstraSync({ apiKey: 'kya_your_api_key' });\n * const result = await client.register({\n *   name: 'My Agent',\n *   model: { modelName: 'gpt-4o', modelProvider: 'openai', modelType: 'llm' },\n * });\n * ```\n *\n * For staging, pass `baseUrl: 'https://staging.astrasync.ai'`.\n */\nexport class AstraSync {\n  private readonly baseUrl: string;\n  private readonly apiKey?: string;\n  private readonly email?: string;\n  private readonly password?: string;\n  private readonly privateKey?: string;\n  private cachedJwt?: string;\n  private jwtExpiresAt?: number;\n\n  constructor(config: AstraSyncConfig = {}) {\n    this.baseUrl = (config.baseUrl || process.env.ASTRASYNC_API_URL || DEFAULT_BASE_URL).replace(\n      /\\/+$/,\n      ''\n    );\n\n    this.apiKey = config.apiKey || process.env.ASTRASYNC_API_KEY;\n    this.email = config.email;\n    this.password = config.password;\n    this.privateKey = config.privateKey;\n\n    if (!this.apiKey && !this.email) {\n      throw new AuthenticationError(\n        'Authentication required. Provide apiKey, or email+password. ' +\n          'Set ASTRASYNC_API_KEY env var or pass config to constructor.'\n      );\n    }\n\n    if (this.email && !this.password) {\n      throw new AuthenticationError('Password is required when using email authentication.');\n    }\n  }\n\n  /**\n   * Register a new AI agent on the AstraSync KYA Platform.\n   * Sends full payload including model, framework, PDLSS, and metadata.\n   */\n  async register(options: RegisterOptions): Promise<RegistrationResponse> {\n    const body: Record<string, unknown> = {\n      name: options.name,\n      ...(options.description && { description: options.description }),\n      ...(options.agentType && { agentType: options.agentType }),\n      ...(options.apiEndpoint && { apiEndpoint: options.apiEndpoint }),\n      ...(options.model && { model: options.model }),\n      ...(options.framework && { framework: options.framework }),\n      ...(options.protocols && { protocols: options.protocols }),\n      ...(options.metadata && { metadata: options.metadata }),\n      ...(options.pdlss && { pdlss: options.pdlss }),\n    };\n\n    return this.request<RegistrationResponse>('POST', '/api/agents/register', body);\n  }\n\n  /**\n   * Look up an agent's public profile by ASTRA ID or UUID.\n   */\n  async verify(agentId: string): Promise<VerifyResponse> {\n    return this.request<VerifyResponse>('GET', `/api/agents/verify/${agentId}`);\n  }\n\n  /**\n   * Check API health.\n   */\n  async health(): Promise<HealthResponse> {\n    const res = await fetch(`${this.baseUrl}/api/health/`);\n    if (!res.ok) {\n      throw new AstraSyncError(`Health check failed: ${res.status}`, res.status);\n    }\n    return res.json() as Promise<HealthResponse>;\n  }\n\n  // ── Private helpers ──────────────────────────────────────────────\n\n  private async request<T>(method: string, endpoint: string, body?: unknown): Promise<T> {\n    const url = `${this.baseUrl}${endpoint}`;\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n    };\n\n    // Set auth header\n    const token = await this.getAuthToken();\n    headers['Authorization'] = `Bearer ${token}`;\n\n    // Sign request if private key is configured\n    if (this.privateKey) {\n      const signature = await this.signRequest(method, endpoint, body || {});\n      headers['X-AstraSync-Signature'] = signature;\n    }\n\n    const res = await fetch(url, {\n      method,\n      headers,\n      ...(body ? { body: JSON.stringify(body) } : {}),\n    });\n\n    if (!res.ok) {\n      const errorBody = (await res\n        .json()\n        .catch(() => ({ error: res.statusText }))) as ApiErrorResponse;\n\n      // Handle KYD_REQUIRED specifically\n      if (res.status === 403 && errorBody.code === 'KYD_REQUIRED') {\n        throw new KYDRequiredError(errorBody);\n      }\n\n      throw new AstraSyncError(\n        errorBody.error || `Request failed: ${res.status}`,\n        res.status,\n        errorBody.code\n      );\n    }\n\n    return res.json() as Promise<T>;\n  }\n\n  private async getAuthToken(): Promise<string> {\n    // API key auth — use directly\n    if (this.apiKey) {\n      return this.apiKey;\n    }\n\n    // Email+password — login and cache JWT\n    if (this.cachedJwt && this.jwtExpiresAt && Date.now() < this.jwtExpiresAt) {\n      return this.cachedJwt;\n    }\n\n    const res = await fetch(`${this.baseUrl}/api/auth/login`, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ email: this.email, password: this.password }),\n    });\n\n    if (!res.ok) {\n      const errorBody = (await res.json().catch(() => ({}))) as Record<string, unknown>;\n      throw new AuthenticationError(\n        (errorBody.message as string) || (errorBody.error as string) || 'Login failed'\n      );\n    }\n\n    const data = (await res.json()) as { data: { token: string } };\n    this.cachedJwt = data.data.token;\n    // Cache for 6 days (tokens expire in 7)\n    this.jwtExpiresAt = Date.now() + 6 * 24 * 60 * 60 * 1000;\n\n    return this.cachedJwt;\n  }\n\n  /**\n   * Sign a request using secp256k1 (ethers.js).\n   * Canonical message format: METHOD:ENDPOINT:SORTED_JSON_BODY\n   * Must match apps/backend/src/services/signature-verify.service.ts exactly.\n   */\n  private async signRequest(method: string, endpoint: string, body: unknown): Promise<string> {\n    const { Wallet } = await import('ethers');\n    const sorted = this.sortObjectKeys(body);\n    const canonical = `${method}:${endpoint}:${JSON.stringify(sorted)}`;\n    const wallet = new Wallet(this.privateKey!);\n    return wallet.signMessage(canonical);\n  }\n\n  /** Recursively sort object keys for canonical JSON representation. */\n  private sortObjectKeys(obj: unknown): unknown {\n    if (obj === null || typeof obj !== 'object') {\n      return obj;\n    }\n    if (Array.isArray(obj)) {\n      return obj.map((item) => this.sortObjectKeys(item));\n    }\n    const sorted: Record<string, unknown> = {};\n    for (const key of Object.keys(obj).sort()) {\n      sorted[key] = this.sortObjectKeys((obj as Record<string, unknown>)[key]);\n    }\n    return sorted;\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/registration/errors.ts","../../src/registration/api.ts"],"sourcesContent":["import type { ApiErrorResponse } from './types';\n\n/** Base error class for AstraSync SDK errors. */\nexport class AstraSyncError extends Error {\n  public readonly code?: string;\n  public readonly statusCode: number;\n\n  constructor(message: string, statusCode: number, code?: string) {\n    super(message);\n    this.name = 'AstraSyncError';\n    this.statusCode = statusCode;\n    this.code = code;\n  }\n}\n\n/** Thrown when KYD verification is required before agent registration. */\nexport class KYDRequiredError extends AstraSyncError {\n  public readonly kydUrl: string;\n  public readonly ownerNotified: boolean;\n\n  constructor(response: ApiErrorResponse) {\n    const kydUrl = response.kydUrl || 'https://astrasync.ai/developer-profile';\n    super(\n      `KYD verification required before registering agents.\\nComplete your KYD profile at: ${kydUrl}`,\n      403,\n      'KYD_REQUIRED'\n    );\n    this.name = 'KYDRequiredError';\n    this.kydUrl = kydUrl;\n    this.ownerNotified = response.ownerNotified || false;\n  }\n}\n\n/** Thrown when authentication fails. */\nexport class AuthenticationError extends AstraSyncError {\n  constructor(message: string) {\n    super(message, 401, 'AUTH_FAILED');\n    this.name = 'AuthenticationError';\n  }\n}\n\n/**\n * Thrown by `register({ waitForApproval: true })` when the owner denies the\n * pending registration request. The `reason` field, when present, mirrors the\n * deny note the owner left in the dashboard.\n */\nexport class RegistrationDeniedError extends AstraSyncError {\n  public readonly requestId: string;\n  public readonly reason?: string;\n\n  constructor(requestId: string, reason?: string) {\n    super(\n      `Registration request ${requestId} was denied by the account owner.${reason ? ` Reason: ${reason}` : ''}`,\n      403,\n      'REGISTRATION_DENIED'\n    );\n    this.name = 'RegistrationDeniedError';\n    this.requestId = requestId;\n    this.reason = reason;\n  }\n}\n\n/**\n * Thrown by `register({ waitForApproval: true })` when the pending request\n * passes its 14-day TTL with no owner decision. The agent must re-submit.\n */\nexport class RegistrationExpiredError extends AstraSyncError {\n  public readonly requestId: string;\n\n  constructor(requestId: string) {\n    super(\n      `Registration request ${requestId} expired before the owner approved it. Submit a new registration request.`,\n      410,\n      'REGISTRATION_EXPIRED'\n    );\n    this.name = 'RegistrationExpiredError';\n    this.requestId = requestId;\n  }\n}\n\n/**\n * Thrown by `register({ waitForApproval: true })` when the caller's local\n * `timeoutMs` elapses before the owner makes a decision. The request is still\n * live server-side — poll `pollRegistration(requestId)` to resume waiting, or\n * call `waitForApproval` again with a longer timeout.\n */\nexport class RegistrationTimeoutError extends AstraSyncError {\n  public readonly requestId: string;\n\n  constructor(requestId: string) {\n    super(\n      `Timed out waiting for owner approval of registration request ${requestId}. The request is still active server-side; poll the request to resume waiting.`,\n      408,\n      'REGISTRATION_TIMEOUT'\n    );\n    this.name = 'RegistrationTimeoutError';\n    this.requestId = requestId;\n  }\n}\n","import type {\n  AstraSyncConfig,\n  RegisterOptions,\n  RegisterResult,\n  WaitForApprovalOptions,\n  PendingRegistrationResponse,\n  PollRegistrationResult,\n  RegistrationResponse,\n  VerifyResponse,\n  HealthResponse,\n  ApiErrorResponse,\n  AgentRecord,\n} from './types';\nimport {\n  AstraSyncError,\n  KYDRequiredError,\n  AuthenticationError,\n  RegistrationDeniedError,\n  RegistrationExpiredError,\n  RegistrationTimeoutError,\n} from './errors';\n\nconst DEFAULT_BASE_URL = 'https://astrasync.ai';\n\nconst sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));\n\n/**\n * AstraSync SDK client for registering and managing AI agents.\n *\n * @example\n * ```typescript\n * const client = new AstraSync({ apiKey: 'kya_your_api_key' });\n * const result = await client.register({\n *   name: 'My Agent',\n *   model: { modelName: 'gpt-4o', modelProvider: 'openai', modelType: 'llm' },\n * });\n * ```\n *\n * For staging, pass `baseUrl: 'https://staging.astrasync.ai'`.\n */\nexport class AstraSync {\n  private readonly baseUrl: string;\n  private readonly apiKey?: string;\n  private readonly email?: string;\n  private readonly password?: string;\n  private readonly privateKey?: string;\n  private cachedJwt?: string;\n  private jwtExpiresAt?: number;\n\n  constructor(config: AstraSyncConfig = {}) {\n    this.baseUrl = (config.baseUrl || process.env.ASTRASYNC_API_URL || DEFAULT_BASE_URL).replace(\n      /\\/+$/,\n      ''\n    );\n\n    this.apiKey = config.apiKey || process.env.ASTRASYNC_API_KEY;\n    this.email = config.email;\n    this.password = config.password;\n    this.privateKey = config.privateKey;\n\n    if (!this.apiKey && !this.email) {\n      throw new AuthenticationError(\n        'Authentication required. Provide apiKey, or email+password. ' +\n          'Set ASTRASYNC_API_KEY env var or pass config to constructor.'\n      );\n    }\n\n    if (this.email && !this.password) {\n      throw new AuthenticationError('Password is required when using email authentication.');\n    }\n  }\n\n  /**\n   * Register a new AI agent on the AstraSync KYA Platform.\n   *\n   * The backend response depends on auth context:\n   * - **Crypto-keypair signed** (`privateKey` configured): synchronous 201,\n   *   returns `{ status: 'active', agent }`.\n   * - **API-key only** (no signature): 202 pending, returns\n   *   `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The\n   *   owner is notified by email and a dashboard alert is emitted; the agent\n   *   becomes active only after the owner approves.\n   *\n   * Blocking mode: pass `{ waitForApproval: true }` to have the SDK poll the\n   * request until it resolves, then return the live agent record. The promise\n   * rejects with `RegistrationDeniedError`, `RegistrationExpiredError`, or\n   * `RegistrationTimeoutError` on the corresponding terminal states.\n   *\n   * @example Non-blocking (default — best for serverless / scheduled agents):\n   * ```typescript\n   * const result = await sdk.register({ name, pdlss });\n   * if (result.status === 'pending_approval') {\n   *   storeRequestId(result.requestId);\n   *   return; // function exits; resume later via pollRegistration()\n   * }\n   * ```\n   *\n   * @example Blocking (best for long-running services + CLI):\n   * ```typescript\n   * const agent = await sdk.register({\n   *   name, pdlss, waitForApproval: true, timeoutMs: 600_000,\n   *   onPending: ({ ageMs }) => console.log(`waiting ${ageMs}ms`),\n   * });\n   * ```\n   */\n  async register(\n    options: RegisterOptions & WaitForApprovalOptions\n  ): Promise<RegisterResult | AgentRecord> {\n    const body: Record<string, unknown> = {\n      name: options.name,\n      ...(options.description && { description: options.description }),\n      ...(options.agentType && { agentType: options.agentType }),\n      ...(options.apiEndpoint && { apiEndpoint: options.apiEndpoint }),\n      ...(options.model && { model: options.model }),\n      ...(options.framework && { framework: options.framework }),\n      ...(options.protocols && { protocols: options.protocols }),\n      ...(options.metadata && { metadata: options.metadata }),\n      ...(options.pdlss && { pdlss: options.pdlss }),\n    };\n\n    const { status, body: raw } = await this.requestWithStatus<\n      RegistrationResponse | PendingRegistrationResponse\n    >('POST', '/api/agents/register', body);\n\n    if (status === 201) {\n      const active: RegisterResult = {\n        status: 'active',\n        agent: (raw as RegistrationResponse).data.agent,\n      };\n      return active;\n    }\n\n    // 202 Accepted — owner approval required.\n    const pendingBody = raw as PendingRegistrationResponse;\n    const pending: RegisterResult = {\n      status: 'pending_approval',\n      requestId: pendingBody.requestId,\n      expiresAt: pendingBody.expiresAt,\n      pollUrl: pendingBody.pollUrl,\n      message: pendingBody.message,\n    };\n\n    if (!options.waitForApproval) return pending;\n\n    return this.waitForApproval(pendingBody.requestId, options);\n  }\n\n  /**\n   * Poll the current state of a pending-approval registration request.\n   *\n   * Useful for caller-driven polling when `waitForApproval: false` (the\n   * default). The endpoint is unauthenticated — pass the `requestId` that\n   * was returned from the 202 response.\n   *\n   * @returns `state: 'pending'` while awaiting; `'approved'` carries the\n   *          minted agent in `agent`; `'denied'` may carry the owner's\n   *          `reason`; `'expired'` is terminal after 14 days.\n   */\n  async pollRegistration(requestId: string): Promise<PollRegistrationResult> {\n    const url = `${this.baseUrl}/api/agents/request-registration/${requestId}`;\n    const res = await fetch(url, { headers: { Accept: 'application/json' } });\n    if (!res.ok) {\n      const errBody = (await res.json().catch(() => ({}))) as ApiErrorResponse;\n      throw new AstraSyncError(\n        errBody.error || `pollRegistration failed: ${res.status}`,\n        res.status,\n        errBody.code\n      );\n    }\n    return (await res.json()) as PollRegistrationResult;\n  }\n\n  /**\n   * Block until a pending registration request resolves to a terminal state.\n   * Resolves to the live `AgentRecord` on approval; rejects with the matching\n   * Registration*Error on deny/expire/timeout. Usually called via\n   * `register({ waitForApproval: true })`, but exposed for callers that want\n   * to fire-and-forget the initial register call and resume waiting later\n   * (e.g. after restoring a stored `requestId` on cold start).\n   */\n  async waitForApproval(\n    requestId: string,\n    options: WaitForApprovalOptions = {}\n  ): Promise<AgentRecord> {\n    const timeoutMs = options.timeoutMs ?? 10 * 60 * 1000;\n    const pollIntervalMs = options.pollIntervalMs ?? 5_000;\n    const start = Date.now();\n    const deadline = start + timeoutMs;\n\n    while (Date.now() < deadline) {\n      const result = await this.pollRegistration(requestId);\n      const ageMs = Date.now() - start;\n      options.onPending?.({ requestId, ageMs });\n\n      if (result.state === 'approved') {\n        if (!result.agent) {\n          throw new AstraSyncError(\n            `Registration ${requestId} reported approved but no agent payload returned.`,\n            500\n          );\n        }\n        return result.agent;\n      }\n      if (result.state === 'denied') {\n        throw new RegistrationDeniedError(requestId, result.reason);\n      }\n      if (result.state === 'expired') {\n        throw new RegistrationExpiredError(requestId);\n      }\n      await sleep(pollIntervalMs);\n    }\n    throw new RegistrationTimeoutError(requestId);\n  }\n\n  /**\n   * Look up an agent's public profile by ASTRA ID or UUID.\n   */\n  async verify(agentId: string): Promise<VerifyResponse> {\n    return this.request<VerifyResponse>('GET', `/api/agents/verify/${agentId}`);\n  }\n\n  /**\n   * Check API health.\n   */\n  async health(): Promise<HealthResponse> {\n    const res = await fetch(`${this.baseUrl}/api/health/`);\n    if (!res.ok) {\n      throw new AstraSyncError(`Health check failed: ${res.status}`, res.status);\n    }\n    return res.json() as Promise<HealthResponse>;\n  }\n\n  // ── Private helpers ──────────────────────────────────────────────\n\n  private async request<T>(method: string, endpoint: string, body?: unknown): Promise<T> {\n    const { body: parsed } = await this.requestWithStatus<T>(method, endpoint, body);\n    return parsed;\n  }\n\n  /**\n   * Variant of {@link request} that also returns the HTTP status code, so\n   * callers can branch on 201 vs 202 (or other success codes) without losing\n   * type information about the response body.\n   */\n  private async requestWithStatus<T>(\n    method: string,\n    endpoint: string,\n    body?: unknown\n  ): Promise<{ status: number; body: T }> {\n    const url = `${this.baseUrl}${endpoint}`;\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n    };\n\n    // Set auth header\n    const token = await this.getAuthToken();\n    headers['Authorization'] = `Bearer ${token}`;\n\n    // Sign request if private key is configured\n    if (this.privateKey) {\n      const signature = await this.signRequest(method, endpoint, body || {});\n      headers['X-AstraSync-Signature'] = signature;\n    }\n\n    const res = await fetch(url, {\n      method,\n      headers,\n      ...(body ? { body: JSON.stringify(body) } : {}),\n    });\n\n    if (!res.ok) {\n      const errorBody = (await res\n        .json()\n        .catch(() => ({ error: res.statusText }))) as ApiErrorResponse;\n\n      // Handle KYD_REQUIRED specifically\n      if (res.status === 403 && errorBody.code === 'KYD_REQUIRED') {\n        throw new KYDRequiredError(errorBody);\n      }\n\n      throw new AstraSyncError(\n        errorBody.error || `Request failed: ${res.status}`,\n        res.status,\n        errorBody.code\n      );\n    }\n\n    return { status: res.status, body: (await res.json()) as T };\n  }\n\n  private async getAuthToken(): Promise<string> {\n    // API key auth — use directly\n    if (this.apiKey) {\n      return this.apiKey;\n    }\n\n    // Email+password — login and cache JWT\n    if (this.cachedJwt && this.jwtExpiresAt && Date.now() < this.jwtExpiresAt) {\n      return this.cachedJwt;\n    }\n\n    const res = await fetch(`${this.baseUrl}/api/auth/login`, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ email: this.email, password: this.password }),\n    });\n\n    if (!res.ok) {\n      const errorBody = (await res.json().catch(() => ({}))) as Record<string, unknown>;\n      throw new AuthenticationError(\n        (errorBody.message as string) || (errorBody.error as string) || 'Login failed'\n      );\n    }\n\n    const data = (await res.json()) as { data: { token: string } };\n    this.cachedJwt = data.data.token;\n    // Cache for 6 days (tokens expire in 7)\n    this.jwtExpiresAt = Date.now() + 6 * 24 * 60 * 60 * 1000;\n\n    return this.cachedJwt;\n  }\n\n  /**\n   * Sign a request using secp256k1 (ethers.js).\n   * Canonical message format: METHOD:ENDPOINT:SORTED_JSON_BODY\n   * Must match apps/backend/src/services/signature-verify.service.ts exactly.\n   */\n  private async signRequest(method: string, endpoint: string, body: unknown): Promise<string> {\n    const { Wallet } = await import('ethers');\n    const sorted = this.sortObjectKeys(body);\n    const canonical = `${method}:${endpoint}:${JSON.stringify(sorted)}`;\n    const wallet = new Wallet(this.privateKey!);\n    return wallet.signMessage(canonical);\n  }\n\n  /** Recursively sort object keys for canonical JSON representation. */\n  private sortObjectKeys(obj: unknown): unknown {\n    if (obj === null || typeof obj !== 'object') {\n      return obj;\n    }\n    if (Array.isArray(obj)) {\n      return obj.map((item) => this.sortObjectKeys(item));\n    }\n    const sorted: Record<string, unknown> = {};\n    for (const key of Object.keys(obj).sort()) {\n      sorted[key] = this.sortObjectKeys((obj as Record<string, unknown>)[key]);\n    }\n    return sorted;\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrasyncai/verification-gateway",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "AstraSync KYA Platform SDK — counterparty verification gateway (verify incoming requests) + agent registration (register AI agents with the KYA backend).",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",