@letsping/sdk 0.3.1 → 0.3.2

package/{src/index.d.ts → dist/index.d.mts}

@@ -1,5 +1,5 @@
-export type Priority = "low" | "medium" | "high" | "critical";
-export interface RequestOptions {
+type Priority = "low" | "medium" | "high" | "critical";
+interface RequestOptions {
     service: string;
     action: string;
     payload: Record<string, any>;
@@ -7,7 +7,7 @@ export interface RequestOptions {
     schema?: Record<string, any>;
     timeoutMs?: number;
 }
-export interface Decision {
+interface Decision {
     status: "APPROVED" | "REJECTED" | "APPROVED_WITH_MODIFICATIONS";
     payload: any;
     patched_payload?: any;
@@ -18,7 +18,7 @@ export interface Decision {
         method?: string;
     };
 }
-export interface EscrowEnvelope {
+interface EscrowEnvelope {
     id: string;
     event: string;
     data: any;
@@ -31,18 +31,18 @@ export interface EscrowEnvelope {
         ap2_mandate?: any;
     };
 }
-export declare function verifyEscrow(event: EscrowEnvelope, secret: string): boolean;
-export interface AgentCallPayload {
+declare function verifyEscrow(event: EscrowEnvelope, secret: string): boolean;
+interface AgentCallPayload {
     project_id: string;
     service: string;
     action: string;
     payload: any;
 }
-export declare function signAgentCall(agentId: string, secret: string, call: AgentCallPayload): {
+declare function signAgentCall(agentId: string, secret: string, call: AgentCallPayload): {
     agent_id: string;
     agent_signature: string;
 };
-export declare function signIngestBody(agentId: string, secret: string, body: {
+declare function signIngestBody(agentId: string, secret: string, body: {
     project_id: string;
     service: string;
     action: string;
@@ -55,9 +55,9 @@ export declare function signIngestBody(agentId: string, secret: string, body: {
     agent_id: string;
     agent_signature: string;
 };
-export declare function verifyAgentSignature(agentId: string, secret: string, call: AgentCallPayload, signature: string): boolean;
+declare function verifyAgentSignature(agentId: string, secret: string, call: AgentCallPayload, signature: string): boolean;
 
-export interface AgentWorkspaceCredentials {
+interface AgentWorkspaceCredentials {
     project_id: string;
     api_key: string;
     ingest_url: string;
@@ -67,25 +67,25 @@ export interface AgentWorkspaceCredentials {
     org_id?: string;
     docs_url?: string;
 }
-export declare function createAgentWorkspace(options?: { baseUrl?: string }): Promise<AgentWorkspaceCredentials>;
+declare function createAgentWorkspace(options?: { baseUrl?: string }): Promise<AgentWorkspaceCredentials>;
 
-export interface IngestWithAgentSignatureOptions {
+interface IngestWithAgentSignatureOptions {
     projectId: string;
     ingestUrl: string;
     apiKey: string;
 }
-export interface IngestPayload {
+interface IngestPayload {
     service: string;
     action: string;
     payload: Record<string, any>;
 }
-export declare function ingestWithAgentSignature(
+declare function ingestWithAgentSignature(
     agentId: string,
     agentSecret: string,
     payload: IngestPayload,
     options: IngestWithAgentSignatureOptions
 ): Promise<Record<string, any>>;
-export declare function chainHandoff(previous: EscrowEnvelope, nextData: {
+declare function chainHandoff(previous: EscrowEnvelope, nextData: {
     service: string;
     action: string;
     payload: any;
@@ -100,20 +100,20 @@ export declare function chainHandoff(previous: EscrowEnvelope, nextData: {
         handoff_signature: string;
     };
 };
-export declare const LETSPING_DOCS_BASE: string;
-export type LetsPingErrorCode = "LETSPING_401_AUTH" | "LETSPING_402_QUOTA" | "LETSPING_403_FORBIDDEN" | "LETSPING_404_NOT_FOUND" | "LETSPING_429_RATE_LIMIT" | "LETSPING_TIMEOUT" | "LETSPING_NETWORK" | "LETSPING_WEBHOOK_INVALID" | string;
-export declare class LetsPingError extends Error {
+declare const LETSPING_DOCS_BASE: string;
+type LetsPingErrorCode = "LETSPING_401_AUTH" | "LETSPING_402_QUOTA" | "LETSPING_403_FORBIDDEN" | "LETSPING_404_NOT_FOUND" | "LETSPING_429_RATE_LIMIT" | "LETSPING_TIMEOUT" | "LETSPING_NETWORK" | "LETSPING_WEBHOOK_INVALID" | string;
+declare class LetsPingError extends Error {
     status?: number;
     code?: LetsPingErrorCode;
     documentationUrl?: string;
     constructor(message: string, status?: number, code?: LetsPingErrorCode, documentationUrl?: string);
 }
-export interface RetryOptions {
+interface RetryOptions {
     maxAttempts?: number;
     initialDelayMs?: number;
     maxDelayMs?: number;
 }
-export interface RequestStatus {
+interface RequestStatus {
     id: string;
     status: "PENDING" | "APPROVED" | "REJECTED";
     payload?: any;
@@ -121,7 +121,7 @@ export interface RequestStatus {
     resolved_at?: string | null;
     actor_id?: string | null;
 }
-export declare class LetsPing {
+declare class LetsPing {
     constructor(apiKey?: string, options?: {
         baseUrl?: string;
         encryptionKey?: string;
@@ -134,3 +134,5 @@ export declare class LetsPing {
     tool(service: string, action: string, priority?: Priority): (context: string | Record<string, any>) => Promise<string>;
     webhookHandler(payloadStr: string, signatureHeader: string, webhookSecret: string): Promise<{ id: string; event: string; data: Decision; state_snapshot?: Record<string, any> }>;
 }
+
+export { type AgentCallPayload, type AgentWorkspaceCredentials, type Decision, type EscrowEnvelope, type IngestPayload, type IngestWithAgentSignatureOptions, LETSPING_DOCS_BASE, LetsPing, LetsPingError, type LetsPingErrorCode, type Priority, type RequestOptions, type RequestStatus, type RetryOptions, chainHandoff, createAgentWorkspace, ingestWithAgentSignature, signAgentCall, signIngestBody, verifyAgentSignature, verifyEscrow };

package/dist/index.d.ts

@@ -0,0 +1,227 @@
+export type Priority = "low" | "medium" | "high" | "critical";
+export interface RequestOptions {
+    service: string;
+    action: string;
+    payload: Record<string, any>;
+    priority?: Priority;
+    schema?: Record<string, any>;
+    state_snapshot?: Record<string, any>;
+    timeoutMs?: number;
+    role?: string;
+    /**
+     * Optional distributed tracing identifiers. If provided, these will be
+     * attached to the request envelope so downstream frameworks can stitch
+     * together multi-agent flows.
+     */
+    trace_id?: string;
+    parent_request_id?: string;
+}
+export interface Decision {
+    status: "APPROVED" | "REJECTED" | "APPROVED_WITH_MODIFICATIONS";
+    payload: any;
+    patched_payload?: any;
+    diff_summary?: any;
+    metadata?: {
+        resolved_at: string;
+        actor_id: string;
+        method?: string;
+    };
+}
+/** Status of a request returned by GET /status/:id. Use with defer() + getRequestStatus() for polling without reading the raw HTTP API. */
+export interface RequestStatus {
+    id: string;
+    status: "PENDING" | "APPROVED" | "REJECTED";
+    payload?: any;
+    patched_payload?: any;
+    resolved_at?: string | null;
+    actor_id?: string | null;
+}
+/** Base URL for error documentation. Errors may include a link to a specific anchor. */
+export declare const LETSPING_DOCS_BASE = "https://letsping.co/docs";
+/** Known error codes for programmatic handling and doc links. */
+export type LetsPingErrorCode = "LETSPING_401_AUTH" | "LETSPING_402_QUOTA" | "LETSPING_403_FORBIDDEN" | "LETSPING_404_NOT_FOUND" | "LETSPING_429_RATE_LIMIT" | "LETSPING_TIMEOUT" | "LETSPING_NETWORK" | "LETSPING_WEBHOOK_INVALID" | string;
+export declare class LetsPingError extends Error {
+    /** HTTP status when the error came from the API (e.g. 402, 429). */
+    readonly status?: number;
+    /** Stable code for handling (e.g. LETSPING_402_QUOTA). Use for branching or logging. */
+    readonly code?: LetsPingErrorCode;
+    /** Link to the relevant doc section. Present when code is set. */
+    readonly documentationUrl?: string;
+    constructor(message: string, status?: number, code?: LetsPingErrorCode, documentationUrl?: string);
+}
+declare function computeDiff(original: any, patched: any): any;
+export interface EscrowEnvelope {
+    id: string;
+    event: string;
+    data: any;
+    escrow?: {
+        mode: "none" | "handoff" | "finalized";
+        handoff_signature: string | null;
+        upstream_agent_id: string | null;
+        downstream_agent_id: string | null;
+        x402_mandate?: any;
+        ap2_mandate?: any;
+    };
+}
+export declare function verifyEscrow(event: EscrowEnvelope, secret: string): boolean;
+export interface AgentCallPayload {
+    project_id: string;
+    service: string;
+    action: string;
+    payload: any;
+}
+export declare function signAgentCall(agentId: string, secret: string, call: AgentCallPayload): {
+    agent_id: string;
+    agent_signature: string;
+};
+export declare function signIngestBody(agentId: string, secret: string, body: {
+    project_id: string;
+    service: string;
+    action: string;
+    payload: any;
+}): {
+    project_id: string;
+    service: string;
+    action: string;
+    payload: any;
+    agent_id: string;
+    agent_signature: string;
+};
+/** Credentials returned by createAgentWorkspace. Use api_key for Bearer auth and ingestWithAgentSignature for signed ingest. */
+export interface AgentWorkspaceCredentials {
+    project_id: string;
+    api_key: string;
+    ingest_url: string;
+    agents_register_url: string;
+    agent_id: string;
+    agent_secret: string;
+    org_id?: string;
+    docs_url?: string;
+}
+/**
+ * Request a signup token, redeem it to create a workspace, and register one agent. Returns credentials so the agent can call ingestWithAgentSignature.
+ * Rate limits apply (see letsping.co/docs). Throws on 4xx/5xx or if self-serve signup is disabled.
+ * @param options.baseUrl - App root URL (e.g. https://letsping.co). Defaults to LETSPING_BASE_URL or https://letsping.co.
+ */
+export declare function createAgentWorkspace(options?: {
+    baseUrl?: string;
+}): Promise<AgentWorkspaceCredentials>;
+/** Options for ingestWithAgentSignature. */
+export interface IngestWithAgentSignatureOptions {
+    projectId: string;
+    ingestUrl: string;
+    apiKey: string;
+}
+/** Ingest payload: service, action, and payload. */
+export interface IngestPayload {
+    service: string;
+    action: string;
+    payload: Record<string, any>;
+}
+/**
+ * Build a signed ingest body and POST it to the ingest URL with Bearer apiKey. Returns the JSON response; throws on non-2xx.
+ * Use this so the agent quickstart does not require hand-rolled HMAC or curl. See also: signIngestBody.
+ */
+export declare function ingestWithAgentSignature(agentId: string, agentSecret: string, payload: IngestPayload, options: IngestWithAgentSignatureOptions): Promise<Record<string, any>>;
+export declare function verifyAgentSignature(agentId: string, secret: string, call: AgentCallPayload, signature: string): boolean;
+export declare function chainHandoff(previous: EscrowEnvelope, nextData: {
+    service: string;
+    action: string;
+    payload: any;
+    upstream_agent_id: string;
+    downstream_agent_id: string;
+}, secret: string): {
+    payload: any;
+    escrow: {
+        mode: "handoff";
+        upstream_agent_id: string;
+        downstream_agent_id: string;
+        handoff_signature: string;
+    };
+};
+/** Optional retry config for ingest and status calls. Disabled when maxAttempts is 1 or omitted. */
+export interface RetryOptions {
+    /** Max attempts per request (default 1 = no retry). Try 3 for transient resilience. */
+    maxAttempts?: number;
+    /** Initial delay in ms before first retry (default 1000). */
+    initialDelayMs?: number;
+    /** Cap on delay between retries in ms (default 10000). */
+    maxDelayMs?: number;
+}
+export declare class LetsPing {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly encryptionKey;
+    private readonly retry;
+    constructor(apiKey?: string, options?: {
+        baseUrl?: string;
+        encryptionKey?: string;
+        retry?: RetryOptions;
+    });
+    private _encrypt;
+    private _decrypt;
+    private _prepareStateUpload;
+    /**
+     * Send a request and block until a human approves or rejects it (or timeout). Use for HITL steps in your agent.
+     * @param options - service, action, payload; optional priority, schema, state_snapshot, timeoutMs, role
+     * @returns Decision with status APPROVED | REJECTED | APPROVED_WITH_MODIFICATIONS and payload (or patched_payload)
+     * @throws LetsPingError with code/documentationUrl on API or network errors, or LETSPING_TIMEOUT if no decision in time
+     * @see https://letsping.co/docs#ask
+     */
+    ask(options: RequestOptions): Promise<Decision>;
+    /**
+     * Fetch the current status of a request by id. Use after defer() to poll until status is APPROVED or REJECTED without calling the raw HTTP API.
+     * @param id - Request id returned from defer()
+     * @returns RequestStatus with status PENDING | APPROVED | REJECTED, payload, resolved_at, actor_id
+     * @see https://letsping.co/docs#requests
+     */
+    getRequestStatus(id: string): Promise<RequestStatus>;
+    /**
+     * Send a request and return immediately with the request id. Poll with getRequestStatus(id) or waitForDecision(id) until resolved.
+     * Use for async flows (e.g. webhook rehydration) where you do not want to block in-process.
+     * @param options - service, action, payload; optional priority, schema, state_snapshot, role
+     * @returns { id } - use id with getRequestStatus(id) or waitForDecision(id)
+     * @see https://letsping.co/docs#defer
+     */
+    defer(options: RequestOptions): Promise<{
+        id: string;
+    }>;
+    private request;
+    private _delay;
+    /**
+     * Poll for a decision on a request created with defer(). Blocks until status is APPROVED/REJECTED or timeout.
+     * @param id - request id from defer()
+     * @param options - originalPayload (fallback if payload not in response), timeoutMs (default 24h)
+     * @returns Decision same shape as ask()
+     * @see https://letsping.co/docs#requests
+     */
+    waitForDecision(id: string, options?: {
+        originalPayload?: Record<string, any>;
+        timeoutMs?: number;
+    }): Promise<Decision>;
+    /**
+     * Build a callable tool (e.g. for LangChain) that runs ask(service, action, payload) and returns a result string.
+     * @param service - LetsPing service name
+     * @param action - action name
+     * @param priority - optional priority (default medium)
+     * @returns Async function(context) => string; context can be JSON string or object
+     * @see https://letsping.co/docs#tool
+     */
+    tool(service: string, action: string, priority?: Priority): (context: string | Record<string, any>) => Promise<string>;
+    /**
+     * Validate and parse an incoming LetsPing webhook body. Verifies signature and optionally fetches/decrypts state_snapshot.
+     * @param payloadStr - raw request body (e.g. await req.text())
+     * @param signatureHeader - x-letsping-signature header
+     * @param webhookSecret - secret from dashboard → Settings → Webhooks
+     * @returns { id, event, data, state_snapshot } for resuming your workflow
+     * @throws LetsPingError with code LETSPING_WEBHOOK_INVALID and documentationUrl on invalid signature or replay
+     * @see https://letsping.co/docs#webhooks
+     */
+    webhookHandler(payloadStr: string, signatureHeader: string, webhookSecret: string): Promise<{
+        id: string;
+        event: string;
+        data: Decision;
+        state_snapshot?: Record<string, any>;
+    }>;
+}
+export { computeDiff };