@agledger/sdk 1.1.0 → 2.0.0

package/dist/scopes.d.ts

@@ -0,0 +1,41 @@
+/**
+ * AGLedger™ SDK — API Key Scopes
+ * Patent Pending. Copyright 2026 AGLedger LLC. All rights reserved.
+ *
+ * Scopes narrow what a key can do within its role's ceiling.
+ * null scopes = full access for the role (backward compat).
+ */
+export declare const Scopes: {
+    readonly MANDATES_READ: "mandates:read";
+    readonly MANDATES_WRITE: "mandates:write";
+    readonly RECEIPTS_READ: "receipts:read";
+    readonly RECEIPTS_WRITE: "receipts:write";
+    readonly WEBHOOKS_READ: "webhooks:read";
+    readonly WEBHOOKS_MANAGE: "webhooks:manage";
+    readonly AUDIT_READ: "audit:read";
+    readonly AUDIT_ANALYZE: "audit:analyze";
+    readonly COMPLIANCE_READ: "compliance:read";
+    readonly COMPLIANCE_WRITE: "compliance:write";
+    readonly AGENTS_READ: "agents:read";
+    readonly AGENTS_MANAGE: "agents:manage";
+    readonly DISPUTES_READ: "disputes:read";
+    readonly DISPUTES_MANAGE: "disputes:manage";
+    readonly DASHBOARD_READ: "dashboard:read";
+    readonly EVENTS_READ: "events:read";
+    readonly SIGNALS_READ: "signals:read";
+    readonly REPUTATION_READ: "reputation:read";
+    readonly ADMIN_KEYS: "admin:keys";
+    readonly ADMIN_SYSTEM: "admin:system";
+    readonly ADMIN_TRUST: "admin:trust";
+};
+export type Scope = (typeof Scopes)[keyof typeof Scopes];
+/** Scope profile definition. */
+export interface ScopeProfile {
+    name: string;
+    description: string;
+    scopes: readonly Scope[];
+}
+/** Pre-defined scope profiles matching the API. */
+export declare const ScopeProfiles: Record<string, ScopeProfile>;
+export type ScopeProfileName = 'sidecar' | 'dashboard' | 'iac-pipeline' | 'agent-full' | 'agent-readonly' | (string & {});
+//# sourceMappingURL=scopes.d.ts.map

package/dist/scopes.js

@@ -0,0 +1,67 @@
+/**
+ * AGLedger™ SDK — API Key Scopes
+ * Patent Pending. Copyright 2026 AGLedger LLC. All rights reserved.
+ *
+ * Scopes narrow what a key can do within its role's ceiling.
+ * null scopes = full access for the role (backward compat).
+ */
+export const Scopes = {
+    // Mandate lifecycle
+    MANDATES_READ: 'mandates:read',
+    MANDATES_WRITE: 'mandates:write',
+    // Receipts
+    RECEIPTS_READ: 'receipts:read',
+    RECEIPTS_WRITE: 'receipts:write',
+    // Webhooks
+    WEBHOOKS_READ: 'webhooks:read',
+    WEBHOOKS_MANAGE: 'webhooks:manage',
+    // Audit & compliance
+    AUDIT_READ: 'audit:read',
+    AUDIT_ANALYZE: 'audit:analyze',
+    COMPLIANCE_READ: 'compliance:read',
+    COMPLIANCE_WRITE: 'compliance:write',
+    // Agents
+    AGENTS_READ: 'agents:read',
+    AGENTS_MANAGE: 'agents:manage',
+    // Disputes
+    DISPUTES_READ: 'disputes:read',
+    DISPUTES_MANAGE: 'disputes:manage',
+    // Dashboard & events
+    DASHBOARD_READ: 'dashboard:read',
+    EVENTS_READ: 'events:read',
+    SIGNALS_READ: 'signals:read',
+    REPUTATION_READ: 'reputation:read',
+    // Administration
+    ADMIN_KEYS: 'admin:keys',
+    ADMIN_SYSTEM: 'admin:system',
+    ADMIN_TRUST: 'admin:trust',
+};
+/** Pre-defined scope profiles matching the API. */
+export const ScopeProfiles = {
+    sidecar: {
+        name: 'sidecar',
+        description: 'Governance sidecar — mandate and receipt operations',
+        scopes: [Scopes.MANDATES_READ, Scopes.MANDATES_WRITE, Scopes.RECEIPTS_WRITE, Scopes.WEBHOOKS_MANAGE],
+    },
+    dashboard: {
+        name: 'dashboard',
+        description: 'Read-only monitoring and audit',
+        scopes: [Scopes.DASHBOARD_READ, Scopes.AUDIT_READ, Scopes.EVENTS_READ, Scopes.SIGNALS_READ, Scopes.DISPUTES_READ, Scopes.REPUTATION_READ],
+    },
+    'iac-pipeline': {
+        name: 'iac-pipeline',
+        description: 'Infrastructure provisioning — agents, webhooks, keys',
+        scopes: [Scopes.AGENTS_MANAGE, Scopes.WEBHOOKS_MANAGE, Scopes.ADMIN_KEYS],
+    },
+    'agent-full': {
+        name: 'agent-full',
+        description: 'Standard agent — mandate and receipt operations',
+        scopes: [Scopes.MANDATES_READ, Scopes.MANDATES_WRITE, Scopes.RECEIPTS_WRITE],
+    },
+    'agent-readonly': {
+        name: 'agent-readonly',
+        description: 'Read-only agent — view mandate history',
+        scopes: [Scopes.MANDATES_READ, Scopes.RECEIPTS_READ],
+    },
+};
+//# sourceMappingURL=scopes.js.map

package/dist/types.d.ts

@@ -85,6 +85,7 @@ export interface BulkCreateResult {
         failed: number;
     };
 }
+/** Known values: ACH-PROC-v1, ACH-DLVR-v1, ACH-DATA-v1, ACH-TXN-v1, ACH-ORCH-v1, ACH-COMM-v1, ACH-AUTH-v1, ACH-INFRA-v1, ACH-DEL-v1, ACH-ANALYZE-v1, ACH-COORD-v1. Accepts any string for forward compatibility. */
 export type ContractType = 'ACH-PROC-v1' | 'ACH-DLVR-v1' | 'ACH-DATA-v1' | 'ACH-TXN-v1' | 'ACH-ORCH-v1' | 'ACH-COMM-v1' | 'ACH-AUTH-v1' | 'ACH-INFRA-v1' | 'ACH-DEL-v1' | 'ACH-ANALYZE-v1' | 'ACH-COORD-v1' | (string & {});
 export interface Denomination {
     amount: number;
@@ -381,55 +382,131 @@ export interface SchemaValidationResult {
         schemaPath?: string;
     }>;
 }
-export type MandateStatus = 'DRAFT' | 'PROPOSED' | 'ACCEPTED' | 'COUNTER_PROPOSED' | 'REJECTED' | 'REGISTERED' | 'ACTIVE' | 'PENDING_VERIFICATION' | 'FULFILLED' | 'FAILED' | 'DISPUTED' | 'CANCELLED' | 'REMEDIATED' | 'EXPIRED' | 'RECEIPT_INVALID' | 'RECEIPT_ACCEPTED' | 'VERIFYING' | 'VERIFIED_PASS' | 'VERIFIED_FAIL' | 'CANCELLED_DRAFT' | 'CANCELLED_PRE_WORK' | 'CANCELLED_IN_PROGRESS' | (string & {});
+/** Known values: DRAFT, PROPOSED, ACCEPTED, COUNTER_PROPOSED, REJECTED, REGISTERED, ACTIVE, PENDING_VERIFICATION, FULFILLED, FAILED, DISPUTED, CANCELLED, REMEDIATED, EXPIRED, RECEIPT_INVALID, RECEIPT_ACCEPTED, VERIFYING, VERIFIED_PASS, VERIFIED_FAIL, CANCELLED_DRAFT, CANCELLED_PRE_WORK, CANCELLED_IN_PROGRESS. Accepts any string for forward compatibility. */
+export type MandateStatus = 'DRAFT' | 'PROPOSED' | 'ACCEPTED' | 'COUNTER_PROPOSED' | 'REJECTED' | 'REGISTERED' | 'ACTIVE' | 'PENDING_VERIFICATION' | 'FULFILLED' | 'FAILED' | 'DISPUTED' | 'CANCELLED' | 'REMEDIATED' | 'EXPIRED' | 'RECEIPT_INVALID' | 'RECEIPT_ACCEPTED' | 'VERIFYING' | 'VERIFIED_PASS' | 'VERIFIED_FAIL' | 'CANCELLED_DRAFT' | 'CANCELLED_PRE_WORK' | 'CANCELLED_IN_PROGRESS' | 'REVISION_REQUESTED' | (string & {});
+/** Known values: register, activate, settle, cancel, refund. Accepts any string for forward compatibility. */
 export type MandateTransitionAction = 'register' | 'activate' | 'settle' | 'cancel' | 'refund' | (string & {});
 export type OperatingMode = 'standard' | 'encrypted' | 'cleartext';
+/** Known values: auto, principal, gated. Accepts any string for forward compatibility. */
+export type VerificationMode = 'auto' | 'principal' | 'gated' | (string & {});
 export type RiskClassification = 'unacceptable' | 'high' | 'limited' | 'minimal' | 'unclassified';
+/**
+ * A mandate — a registered commitment between a principal and a performer.
+ * Records what was asked, by whom, and when. The contract is the product.
+ *
+ * @example
+ * ```ts
+ * const mandate = await client.mandates.create({
+ *   enterpriseId: 'ent_123',
+ *   contractType: 'ACH-PROC-v1',
+ *   contractVersion: '1',
+ *   platform: 'internal',
+ *   criteria: { item: 'widgets', maxQuantity: 100, maxUnitPrice: { amount: 20, currency: 'USD' } },
+ * });
+ * ```
+ */
 export interface Mandate {
+    /** Unique mandate ID (UUID). */
     id: string;
+    /** Enterprise that owns this mandate. */
     enterpriseId: string;
+    /** Agent assigned to this mandate, or null if unassigned. */
     agentId: string | null;
+    /** Agentic Contract Specification type (e.g., 'ACH-PROC-v1'). */
     contractType: ContractType;
+    /** Version of the contract schema. */
     contractVersion: string;
+    /** Platform where this mandate operates. */
     platform: string;
+    /** External reference ID on the platform. */
     platformRef?: string;
+    /** Current lifecycle status. Use `getValidTransitions()` to see allowed next states. */
     status: MandateStatus;
+    /** Acceptance criteria — what the performer must deliver. Typed per contract type. */
     criteria: Record<string, unknown>;
+    /** Tolerance bands for numeric criteria (e.g., quantity_pct: 5 allows 5% variance). */
     tolerance?: Record<string, unknown>;
+    /** ISO 8601 deadline for completion. */
     deadline?: string;
+    /** Commission percentage for the performing agent. */
     commissionPct?: number;
+    /** Operating mode: standard (default), encrypted, or cleartext. */
     operatingMode?: OperatingMode;
+    /** Verification mode: auto (rules auto-settle), principal (hold for verdict), gated (rules then verdict). */
+    verificationMode?: VerificationMode;
+    /** EU AI Act risk classification. */
     riskClassification?: RiskClassification;
+    /** EU AI Act domain (e.g., 'healthcare', 'finance'). */
     euAiActDomain?: string;
+    /** Human oversight configuration for EU AI Act compliance. */
     humanOversight?: Record<string, unknown>;
+    /** Performer's response to a proposed mandate. */
     acceptanceStatus?: 'PENDING' | 'ACCEPTED' | 'REJECTED' | 'COUNTER_PROPOSED';
+    /** Project grouping reference for related mandates. */
     projectRef?: string;
+    /** Parent mandate ID in a delegation chain. */
     parentMandateId?: string;
+    /** Root mandate ID at the top of the delegation chain. */
     rootMandateId?: string;
+    /** Depth in the delegation chain (0 = root). */
     chainDepth?: number;
+    /** Reason provided for the last state transition. */
     lastTransitionReason?: string | null;
+    /** Actor who triggered the last state transition. */
     lastTransitionBy?: string | null;
+    /** Number of receipt submissions so far. */
+    submissionCount: number;
+    /** Maximum allowed submissions, or null for unlimited. */
+    maxSubmissions: number | null;
+    /** Optimistic concurrency version. */
     version: number;
+    /** ISO 8601 creation timestamp. */
     createdAt: string;
+    /** ISO 8601 last update timestamp. */
     updatedAt: string;
+    /** ISO 8601 timestamp when the mandate was activated. */
     activatedAt?: string;
+    /** ISO 8601 timestamp when the mandate was fulfilled. */
     fulfilledAt?: string;
 }
+/**
+ * Parameters for creating a new mandate via enterprise auth.
+ * For agent-to-agent mandates, use {@link CreateAgentMandateParams} with `mandates.createAgent()`.
+ */
 export interface CreateMandateParams {
+    /** Enterprise ID that owns this mandate. */
     enterpriseId: string;
+    /** Contract type (e.g., 'ACH-PROC-v1'). Determines criteria schema. */
     contractType: ContractType;
+    /** Contract schema version. */
     contractVersion: string;
+    /** Platform identifier. */
     platform: string;
+    /** External reference ID on the platform. */
     platformRef?: string;
+    /** Project grouping reference. */
     projectRef?: string;
+    /** Acceptance criteria. Typed per contract type when using generic overload. */
     criteria: Record<string, unknown>;
+    /** Numeric tolerance bands (e.g., `{ quantity_pct: 5 }`). */
     tolerance?: Record<string, unknown>;
+    /** ISO 8601 deadline for completion. */
     deadline?: string;
+    /** Agent ID to assign as performer. */
     agentId?: string;
+    /** Commission percentage for the performing agent. */
     commissionPct?: number;
+    /** Max receipt submissions allowed (1-100). Null/omit for unlimited. */
+    maxSubmissions?: number;
+    /** Operating mode: standard (default), encrypted, or cleartext. */
     operatingMode?: OperatingMode;
+    /** Verification mode: auto (default, rules auto-settle), principal (hold for verdict), gated (rules then verdict). */
+    verificationMode?: VerificationMode;
+    /** EU AI Act risk classification. */
     riskClassification?: RiskClassification;
+    /** EU AI Act domain. */
     euAiActDomain?: string;
+    /** Human oversight configuration. */
     humanOversight?: Record<string, unknown>;
 }
 export interface UpdateMandateParams {
@@ -442,6 +519,7 @@ export interface UpdateMandateParams {
 }
 export interface ListMandatesParams extends ListParams {
     enterpriseId: string;
+    status?: MandateStatus;
 }
 export interface SearchMandatesParams extends ListParams {
     enterpriseId: string;
@@ -473,30 +551,53 @@ export interface CreateAgentMandateParams {
     tolerance?: Record<string, unknown>;
     parentMandateId?: string;
     commissionPct?: number;
+    maxSubmissions?: number;
     deadline?: string;
+    verificationMode?: VerificationMode;
 }
 export interface RespondToMandateParams {
     action: 'accept' | 'reject' | 'counter';
     reason?: string;
     counterTerms?: Record<string, unknown>;
 }
+/** Known values: SUBMITTED, ACCEPTED, REJECTED, INVALID. Accepts any string for forward compatibility. */
 export type ReceiptStatus = 'SUBMITTED' | 'ACCEPTED' | 'REJECTED' | 'INVALID' | (string & {});
+/**
+ * A receipt — structured evidence submitted by a performer claiming completion of a mandate.
+ * The principal reviews the receipt and renders a verdict (accept/reject).
+ */
 export interface Receipt {
+    /** Unique receipt ID (UUID). */
     id: string;
+    /** Mandate this receipt is for. */
     mandateId: string;
+    /** Agent that submitted the receipt. */
     agentId: string;
+    /** Receipt processing status. */
     status: ReceiptStatus;
+    /** Evidence of completion. Typed per contract type. */
     evidence: Record<string, unknown>;
+    /** SHA-256 hash of the evidence payload. */
     evidenceHash?: string;
+    /** Free-text notes from the performer. */
     notes?: string;
+    /** Current verification phase (e.g., 'phase1', 'phase2'). */
     verificationPhase?: string;
+    /** Detailed verification rule results. */
     verificationResult?: Record<string, unknown>;
+    /** Overall verification outcome: PASS, FAIL, or REVIEW_REQUIRED. */
     verificationOutcome?: VerificationOutcome;
+    /** ISO 8601 timestamp when verification completed. */
     verificationCompletedAt?: string;
+    /** Schema validation errors, if the receipt was invalid. */
     validationErrors?: string[] | null;
+    /** Current status of the parent mandate (denormalized for convenience). */
     mandateStatus?: MandateStatus;
+    /** Idempotency key used when submitting. */
     idempotencyKey?: string | null;
+    /** ISO 8601 creation timestamp. */
     createdAt: string;
+    /** ISO 8601 last update timestamp. */
     updatedAt?: string;
 }
 export interface SubmitReceiptParams {
@@ -509,7 +610,9 @@ export interface UpdateReceiptParams {
     evidence?: Record<string, unknown>;
     notes?: string;
 }
+/** Known values: PASS, FAIL, REVIEW_REQUIRED. Accepts any string for forward compatibility. */
 export type VerificationOutcome = 'PASS' | 'FAIL' | 'REVIEW_REQUIRED' | (string & {});
+/** Known values: SETTLE, HOLD, RELEASE. Accepts any string for forward compatibility. */
 export type SettlementSignal = 'SETTLE' | 'HOLD' | 'RELEASE' | (string & {});
 export interface VerificationResult {
     mandateId: string;
@@ -527,6 +630,7 @@ export interface VerificationStatus {
     lastVerifiedAt?: string;
     pendingRules?: string[];
 }
+/** Known values: OPEN, TIER_1_REVIEW, EVIDENCE_WINDOW, TIER_2_REVIEW, ESCALATED, TIER_3_ARBITRATION, RESOLVED, WITHDRAWN. Accepts any string for forward compatibility. */
 export type DisputeStatus = 'OPEN' | 'TIER_1_REVIEW' | 'EVIDENCE_WINDOW' | 'TIER_2_REVIEW' | 'ESCALATED' | 'TIER_3_ARBITRATION' | 'RESOLVED' | 'WITHDRAWN' | (string & {});
 export interface Dispute {
     id: string;
@@ -551,7 +655,8 @@ export interface ResolveDisputeParams {
     resolution: string;
     amount?: number;
 }
-export type WebhookEventType = 'receipt.submitted' | 'receipt.verified' | 'receipt.accepted' | 'receipt.rejected' | 'mandate.created' | 'mandate.registered' | 'mandate.activated' | 'mandate.fulfilled' | 'mandate.failed' | 'mandate.cancelled' | 'mandate.delegated' | 'mandate.released' | 'dispute.created' | 'dispute.resolved' | 'signal.emitted' | 'verification.complete' | (string & {});
+/** Known values: receipt.submitted, receipt.verified, receipt.accepted, receipt.rejected, mandate.created, mandate.registered, mandate.activated, mandate.fulfilled, mandate.failed, mandate.cancelled, mandate.delegated, mandate.released, dispute.created, dispute.resolved, signal.emitted, verification.complete. Accepts any string for forward compatibility. */
+export type WebhookEventType = 'receipt.submitted' | 'receipt.verified' | 'receipt.accepted' | 'receipt.rejected' | 'mandate.created' | 'mandate.registered' | 'mandate.activated' | 'mandate.fulfilled' | 'mandate.failed' | 'mandate.cancelled' | 'mandate.delegated' | 'mandate.released' | 'mandate.revision_requested' | 'dispute.created' | 'dispute.resolved' | 'signal.emitted' | 'verification.complete' | (string & {});
 export interface Webhook {
     id: string;
     url: string;
@@ -596,6 +701,7 @@ export interface WebhookTestResult {
     success?: boolean;
     deliveryId?: string;
 }
+/** Known values: platinum, gold, silver, bronze. Accepts any string for forward compatibility. */
 export type ReputationTier = 'platinum' | 'gold' | 'silver' | 'bronze' | (string & {});
 export interface ReputationScore {
     agentId: string;
@@ -756,6 +862,10 @@ export interface AccountProfile {
     enterpriseId?: string;
     capabilities?: ContractType[];
     sandboxMode?: boolean;
+    /** API key scopes. Null = full access for the role. */
+    scopes?: string[] | null;
+    /** Scope profile name if key was created with a profile. */
+    scopeProfile?: string | null;
     createdAt: string;
 }
 export interface HealthResponse {
@@ -806,8 +916,32 @@ export interface AdminApiKey {
     ownerId: string;
     ownerType: AccountType;
     active: boolean;
+    /** API key scopes. Null = full access for the role. */
+    scopes?: string[] | null;
+    /** Scope profile name if created with a profile. */
+    scopeProfile?: string | null;
     createdAt: string;
     lastUsedAt?: string;
+    expiresAt?: string | null;
+}
+export interface CreateApiKeyParams {
+    ownerId: string;
+    ownerType: AccountType;
+    /** Explicit scopes to set on the key. */
+    scopes?: string[];
+    /** Convenience profile name — expands to a predefined scope array. Takes precedence over `scopes`. */
+    scopeProfile?: string;
+    /** Optional expiration date (ISO 8601). */
+    expiresAt?: string;
+    /** IP allowlist. Null = any IP. */
+    allowedIps?: string[];
+}
+/** Result of creating an API key via the admin endpoint. */
+export interface CreateApiKeyResult {
+    apiKey: string;
+    keyId: string;
+    scopes: string[] | null;
+    scopeProfile: string | null;
 }
 export interface WebhookDlqEntry {
     id: string;
@@ -860,6 +994,7 @@ export interface JsonRpcResponse {
     id?: string | number;
 }
 export type ProxyMode = 'observe' | 'advisory' | 'enforced';
+/** Known values: ALLOWED, BLOCKED, ANNOTATED. Accepts any string for forward compatibility. */
 export type InterceptorAction = 'ALLOWED' | 'BLOCKED' | 'ANNOTATED' | (string & {});
 export type ConfidenceLevel = 'low' | 'medium' | 'high';
 export type SidecarMandateStatus = 'SHADOW' | 'FORMALIZED' | 'DISMISSED';
@@ -1040,6 +1175,7 @@ export interface AlignmentAnalysis {
     missingCategories?: string[];
     recommendations?: string[];
 }
+/** Known values: NOTARIZED, ACCEPTED, COUNTER_PROPOSED, RECEIPT_SUBMITTED, VERDICT_PASS, VERDICT_FAIL. Accepts any string for forward compatibility. */
 export type NotarizeStatus = 'NOTARIZED' | 'ACCEPTED' | 'COUNTER_PROPOSED' | 'RECEIPT_SUBMITTED' | 'VERDICT_PASS' | 'VERDICT_FAIL' | (string & {});
 export interface NotarizedMandate {
     id: string;
@@ -1083,7 +1219,7 @@ export interface NotarizeReceiptResult {
     payload: Record<string, unknown>;
 }
 export interface NotarizeVerdictParams {
-    outcome: 'PASS' | 'FAIL';
+    verdict: 'PASS' | 'FAIL';
     reason?: string;
 }
 export interface NotarizeVerifyParams {
@@ -1099,6 +1235,53 @@ export interface NotarizeHistory {
     mandateId: string;
     transitions: NotarizeTransition[];
 }
+/** Known values: approved, suspended, revoked. Accepts any string for forward compatibility. */
+export type EnterpriseAgentStatus = 'approved' | 'suspended' | 'revoked' | (string & {});
+export interface EnterpriseAgentRecord {
+    enterpriseId: string;
+    agentId: string;
+    status: EnterpriseAgentStatus;
+    approvedBy: string | null;
+    approvedAt: string;
+    suspendedAt: string | null;
+    revokedAt: string | null;
+    reason: string | null;
+}
+export interface ApprovalConfig {
+    agentApprovalRequired: boolean;
+    allowSelfApproval: boolean;
+}
+export interface ApproveAgentParams {
+    reason?: string;
+}
+export interface RevokeAgentParams {
+    reason?: string;
+}
+export interface UpdateAgentStatusParams {
+    status: 'suspended' | 'approved';
+    reason?: string;
+}
+export interface BulkApproveAgentParams {
+    agents: Array<{
+        agentId: string;
+        reason?: string;
+    }>;
+}
+export interface BulkApproveResult {
+    results: Array<{
+        agentId: string;
+        status: 'approved' | 'failed';
+        error?: string;
+    }>;
+    summary: {
+        total: number;
+        approved: number;
+        failed: number;
+    };
+}
+export interface ListEnterpriseAgentsParams extends ListParams {
+    status?: EnterpriseAgentStatus;
+}
 export interface ApiErrorResponse {
     error: string;
     message: string;

package/dist/webhooks/verify.d.ts

@@ -5,6 +5,39 @@
  * Separate export to avoid pulling node:crypto into browser bundles.
  * Import via: import { verifySignature } from '@agledger/sdk/webhooks'
  */
+import type { WebhookEventType, Mandate, Receipt, VerificationResult, Dispute } from '../types.js';
+/** A verified webhook event with typed payload. */
+export interface WebhookEvent<T extends WebhookEventType = WebhookEventType> {
+    /** Event type (e.g., 'mandate.created', 'receipt.submitted'). */
+    type: T;
+    /** Event payload — the resource that triggered the event. */
+    data: T extends `mandate.${string}` ? Mandate : T extends `receipt.${string}` ? Receipt : T extends `verification.${string}` ? VerificationResult : T extends `dispute.${string}` ? Dispute : Record<string, unknown>;
+    /** ISO 8601 timestamp of the event. */
+    timestamp: string;
+    /** Unique event ID. */
+    id?: string;
+}
+/**
+ * Verify a webhook signature and parse the payload in one step.
+ *
+ * @param rawBody - The raw request body string (do NOT parse JSON first)
+ * @param header - The x-agledger-signature header value
+ * @param secrets - One or more webhook secrets (array for key rotation)
+ * @param toleranceSeconds - Max age in seconds (default/max: 300)
+ * @returns Parsed and typed webhook event
+ * @throws Error if signature is invalid or body cannot be parsed
+ *
+ * @example
+ * ```ts
+ * import { constructEvent } from '@agledger/sdk/webhooks';
+ *
+ * const event = constructEvent(rawBody, req.headers['x-agledger-signature'], secret);
+ * if (event.type === 'mandate.created') {
+ *   console.log(event.data.id); // typed as Mandate
+ * }
+ * ```
+ */
+export declare function constructEvent(rawBody: string, header: string, secrets: string | string[], toleranceSeconds?: number): WebhookEvent;
 export interface SignResult {
     header: string;
     timestamp: number;

package/dist/webhooks/verify.js

@@ -7,6 +7,38 @@
  */
 import { createHmac, timingSafeEqual } from 'node:crypto';
 const MAX_TOLERANCE_SECONDS = 300;
+/**
+ * Verify a webhook signature and parse the payload in one step.
+ *
+ * @param rawBody - The raw request body string (do NOT parse JSON first)
+ * @param header - The x-agledger-signature header value
+ * @param secrets - One or more webhook secrets (array for key rotation)
+ * @param toleranceSeconds - Max age in seconds (default/max: 300)
+ * @returns Parsed and typed webhook event
+ * @throws Error if signature is invalid or body cannot be parsed
+ *
+ * @example
+ * ```ts
+ * import { constructEvent } from '@agledger/sdk/webhooks';
+ *
+ * const event = constructEvent(rawBody, req.headers['x-agledger-signature'], secret);
+ * if (event.type === 'mandate.created') {
+ *   console.log(event.data.id); // typed as Mandate
+ * }
+ * ```
+ */
+export function constructEvent(rawBody, header, secrets, toleranceSeconds) {
+    if (!verifySignature(rawBody, header, secrets, toleranceSeconds)) {
+        throw new Error('Webhook signature verification failed');
+    }
+    const parsed = JSON.parse(rawBody);
+    return {
+        type: parsed.type ?? parsed.event ?? 'unknown',
+        data: parsed.data ?? parsed.payload ?? parsed,
+        timestamp: parsed.timestamp ?? parsed.created_at ?? new Date().toISOString(),
+        id: parsed.id ?? parsed.event_id,
+    };
+}
 /**
  * Sign a payload (for testing purposes).
  * Returns the header string, timestamp, and hex signature.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agledger/sdk",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "AGLedger™ SDK — Accountability and audit infrastructure for agentic systems.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -9,11 +9,13 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./webhooks": {
       "types": "./dist/webhooks/verify.d.ts",
-      "import": "./dist/webhooks/verify.js"
+      "import": "./dist/webhooks/verify.js",
+      "default": "./dist/webhooks/verify.js"
     }
   },
   "files": [