@pliuz/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,179 @@
+import { P as PliuzClient, O as Originator } from './client-BABvN_88.cjs';
+export { A as ApiErrorBody, a as ApprovalRequest, b as ApprovalStatus, C as CreateApprovalInput, c as CreateApprovalResponse, D as DEFAULT_BASE_URL, d as DEFAULT_MAX_RETRIES, e as DEFAULT_TIMEOUT_MS, E as ENV_API_KEY, f as ENV_BASE_URL, g as ExecutionInput, h as ExecutionResult, i as ExecutionStatus, j as OriginatorType, k as PliuzClientOptions } from './client-BABvN_88.cjs';
+
+/**
+ * Single source of truth for the package version.
+ * Kept in sync with `package.json` by release tooling at publish time.
+ */
+declare const VERSION: "0.1.0";
+
+/**
+ * Field-level redaction applied client-side BEFORE sending to Pliuz.
+ *
+ * Non-negotiable architectural decision: sensitive fields (PII, secrets, PHI)
+ * must never leave the caller's process in plaintext. The SDK applies
+ * redaction on the client side, transmits the redacted payload, and the
+ * backend never sees the raw values.
+ *
+ * ## Path syntax
+ *
+ *   "customer.ssn"          → payload.customer.ssn
+ *   "items[*].card_number"  → every item's card_number
+ *   "headers.authorization" → payload.headers.authorization
+ *
+ * Limitations (intentional — keep the surface tiny):
+ * - No JSONPath wildcards beyond `[*]`
+ * - No filter expressions
+ * - Missing keys are silently ignored
+ */
+declare const REDACTED_PLACEHOLDER: "<redacted>";
+/**
+ * Returns a deep copy of `payload` with values at `paths` replaced by
+ * `REDACTED_PLACEHOLDER`. Does not mutate the input.
+ *
+ * @example
+ *   applyRedaction({ customer: { ssn: '123-45-6789' } }, ['customer.ssn'])
+ *   // → { customer: { ssn: '<redacted>' } }
+ */
+declare function applyRedaction<T extends Record<string, unknown>>(payload: T, paths: readonly string[] | null | undefined): T;
+
+/**
+ * Error hierarchy for the Pliuz SDK.
+ *
+ * All exceptions extend `PliuzError`. HTTP-level failures use `PliuzApiError`
+ * subclasses keyed by status code, so callers can do narrow `instanceof` checks:
+ *
+ * ```ts
+ * try {
+ *   await pliuz.createApproval(...)
+ * } catch (e) {
+ *   if (e instanceof PliuzAuthError) {
+ *     // refresh API key
+ *   } else if (e instanceof PliuzPolicyError) {
+ *     // no policy matched — define a catch-all
+ *   } else if (e instanceof PliuzApiError) {
+ *     // other 4xx/5xx
+ *   }
+ *   throw e
+ * }
+ * ```
+ */
+declare class PliuzError extends Error {
+    constructor(message: string);
+}
+declare class PliuzNetworkError extends PliuzError {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+declare class PliuzTimeoutError extends PliuzError {
+    constructor(message: string);
+}
+declare class PliuzApiError extends PliuzError {
+    readonly statusCode: number;
+    readonly errorCode: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown> | undefined);
+}
+declare class PliuzValidationError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzAuthError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzForbiddenError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzNotFoundError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzConflictError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzPolicyError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzRateLimitError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzServerError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzRejectedError extends PliuzError {
+    readonly approvalId: string;
+    readonly reason: string | null;
+    constructor(approvalId: string, reason: string | null);
+}
+declare class PliuzApprovalExpiredError extends PliuzError {
+    readonly approvalId: string;
+    constructor(approvalId: string);
+}
+declare class PliuzApprovalTimeoutError extends PliuzError {
+    readonly approvalId: string;
+    readonly timeoutMs: number;
+    constructor(approvalId: string, timeoutMs: number);
+}
+declare function errorForStatus(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>): PliuzApiError;
+
+/**
+ * The `gated()` wrapper — the headline API of the Pliuz TypeScript SDK.
+ *
+ * Wraps any function (sync or async) so every call is gated by a Pliuz
+ * approval request. The wrapped function always returns `Promise<TResult>`
+ * even if the original is synchronous — gating is inherently async because
+ * it involves an HTTP call.
+ *
+ * @example
+ *   import { gated } from '@pliuz/sdk'
+ *
+ *   const issueRefund = gated(
+ *     {
+ *       policy: 'refund',
+ *       redact: ['customer.ssn'],
+ *       toolArgs: (customerId: string, amountCents: number) => ({
+ *         customer_id: customerId,
+ *         amount_cents: amountCents,
+ *       }),
+ *     },
+ *     async (customerId, amountCents) => stripe.refund(customerId, amountCents),
+ *   )
+ *
+ *   const result = await issueRefund('cus_123', 5000)
+ */
+
+declare const DEFAULT_GATED_TIMEOUT_MS = 300000;
+declare const DEFAULT_GATED_POLL_INTERVAL_MS = 2000;
+interface GatedOptions<TArgs extends readonly unknown[]> {
+    /** Policy slug to bind this gate to. Default: backend resolves by toolName. */
+    policy?: string;
+    /** Redaction paths applied to tool_args BEFORE sending. */
+    redact?: readonly string[];
+    /** Override the tool name. Default: `fn.name` (may be empty for anonymous). */
+    toolName?: string;
+    /**
+     * Map the wrapped function's args into a tool_args object.
+     * Default: `(...args) => ({ args })` — wraps all positional args under
+     * a single `args` key. Provide a custom mapper for cleaner audit trails.
+     */
+    toolArgs?: (...args: TArgs) => Record<string, unknown>;
+    /** Max ms to poll for the approval to resolve. Throws on timeout. */
+    timeoutMs?: number;
+    /** Ms between GET /approvals/:id polls. */
+    pollIntervalMs?: number;
+    /** Reuse an existing PliuzClient. Default: `new PliuzClient()`. */
+    client?: PliuzClient;
+    /** Optional context for the human approver. */
+    contextMessages?: readonly string[];
+    /** Optional session id (groups related approvals in the UI). */
+    sessionId?: string;
+    /** Optional originator (default: { type: 'system' }). */
+    originator?: Originator;
+}
+/**
+ * Wrap a function so every call is gated by Pliuz.
+ *
+ * The returned function ALWAYS returns a Promise, even if the input is sync.
+ * This is intentional — gating necessarily involves async HTTP calls.
+ */
+declare function gated<TArgs extends readonly unknown[], TResult>(options: GatedOptions<TArgs>, fn: (...args: TArgs) => Promise<TResult> | TResult): (...args: TArgs) => Promise<TResult>;
+
+export { DEFAULT_GATED_POLL_INTERVAL_MS, DEFAULT_GATED_TIMEOUT_MS, type GatedOptions, Originator, PliuzApiError, PliuzApprovalExpiredError, PliuzApprovalTimeoutError, PliuzAuthError, PliuzClient, PliuzConflictError, PliuzError, PliuzForbiddenError, PliuzNetworkError, PliuzNotFoundError, PliuzPolicyError, PliuzRateLimitError, PliuzRejectedError, PliuzServerError, PliuzTimeoutError, PliuzValidationError, REDACTED_PLACEHOLDER, VERSION, applyRedaction, errorForStatus, gated };

package/dist/index.d.ts

@@ -0,0 +1,179 @@
+import { P as PliuzClient, O as Originator } from './client-BABvN_88.js';
+export { A as ApiErrorBody, a as ApprovalRequest, b as ApprovalStatus, C as CreateApprovalInput, c as CreateApprovalResponse, D as DEFAULT_BASE_URL, d as DEFAULT_MAX_RETRIES, e as DEFAULT_TIMEOUT_MS, E as ENV_API_KEY, f as ENV_BASE_URL, g as ExecutionInput, h as ExecutionResult, i as ExecutionStatus, j as OriginatorType, k as PliuzClientOptions } from './client-BABvN_88.js';
+
+/**
+ * Single source of truth for the package version.
+ * Kept in sync with `package.json` by release tooling at publish time.
+ */
+declare const VERSION: "0.1.0";
+
+/**
+ * Field-level redaction applied client-side BEFORE sending to Pliuz.
+ *
+ * Non-negotiable architectural decision: sensitive fields (PII, secrets, PHI)
+ * must never leave the caller's process in plaintext. The SDK applies
+ * redaction on the client side, transmits the redacted payload, and the
+ * backend never sees the raw values.
+ *
+ * ## Path syntax
+ *
+ *   "customer.ssn"          → payload.customer.ssn
+ *   "items[*].card_number"  → every item's card_number
+ *   "headers.authorization" → payload.headers.authorization
+ *
+ * Limitations (intentional — keep the surface tiny):
+ * - No JSONPath wildcards beyond `[*]`
+ * - No filter expressions
+ * - Missing keys are silently ignored
+ */
+declare const REDACTED_PLACEHOLDER: "<redacted>";
+/**
+ * Returns a deep copy of `payload` with values at `paths` replaced by
+ * `REDACTED_PLACEHOLDER`. Does not mutate the input.
+ *
+ * @example
+ *   applyRedaction({ customer: { ssn: '123-45-6789' } }, ['customer.ssn'])
+ *   // → { customer: { ssn: '<redacted>' } }
+ */
+declare function applyRedaction<T extends Record<string, unknown>>(payload: T, paths: readonly string[] | null | undefined): T;
+
+/**
+ * Error hierarchy for the Pliuz SDK.
+ *
+ * All exceptions extend `PliuzError`. HTTP-level failures use `PliuzApiError`
+ * subclasses keyed by status code, so callers can do narrow `instanceof` checks:
+ *
+ * ```ts
+ * try {
+ *   await pliuz.createApproval(...)
+ * } catch (e) {
+ *   if (e instanceof PliuzAuthError) {
+ *     // refresh API key
+ *   } else if (e instanceof PliuzPolicyError) {
+ *     // no policy matched — define a catch-all
+ *   } else if (e instanceof PliuzApiError) {
+ *     // other 4xx/5xx
+ *   }
+ *   throw e
+ * }
+ * ```
+ */
+declare class PliuzError extends Error {
+    constructor(message: string);
+}
+declare class PliuzNetworkError extends PliuzError {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+declare class PliuzTimeoutError extends PliuzError {
+    constructor(message: string);
+}
+declare class PliuzApiError extends PliuzError {
+    readonly statusCode: number;
+    readonly errorCode: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown> | undefined);
+}
+declare class PliuzValidationError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzAuthError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzForbiddenError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzNotFoundError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzConflictError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzPolicyError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzRateLimitError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzServerError extends PliuzApiError {
+    constructor(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>);
+}
+declare class PliuzRejectedError extends PliuzError {
+    readonly approvalId: string;
+    readonly reason: string | null;
+    constructor(approvalId: string, reason: string | null);
+}
+declare class PliuzApprovalExpiredError extends PliuzError {
+    readonly approvalId: string;
+    constructor(approvalId: string);
+}
+declare class PliuzApprovalTimeoutError extends PliuzError {
+    readonly approvalId: string;
+    readonly timeoutMs: number;
+    constructor(approvalId: string, timeoutMs: number);
+}
+declare function errorForStatus(statusCode: number, errorCode: string, message: string, details?: Record<string, unknown>): PliuzApiError;
+
+/**
+ * The `gated()` wrapper — the headline API of the Pliuz TypeScript SDK.
+ *
+ * Wraps any function (sync or async) so every call is gated by a Pliuz
+ * approval request. The wrapped function always returns `Promise<TResult>`
+ * even if the original is synchronous — gating is inherently async because
+ * it involves an HTTP call.
+ *
+ * @example
+ *   import { gated } from '@pliuz/sdk'
+ *
+ *   const issueRefund = gated(
+ *     {
+ *       policy: 'refund',
+ *       redact: ['customer.ssn'],
+ *       toolArgs: (customerId: string, amountCents: number) => ({
+ *         customer_id: customerId,
+ *         amount_cents: amountCents,
+ *       }),
+ *     },
+ *     async (customerId, amountCents) => stripe.refund(customerId, amountCents),
+ *   )
+ *
+ *   const result = await issueRefund('cus_123', 5000)
+ */
+
+declare const DEFAULT_GATED_TIMEOUT_MS = 300000;
+declare const DEFAULT_GATED_POLL_INTERVAL_MS = 2000;
+interface GatedOptions<TArgs extends readonly unknown[]> {
+    /** Policy slug to bind this gate to. Default: backend resolves by toolName. */
+    policy?: string;
+    /** Redaction paths applied to tool_args BEFORE sending. */
+    redact?: readonly string[];
+    /** Override the tool name. Default: `fn.name` (may be empty for anonymous). */
+    toolName?: string;
+    /**
+     * Map the wrapped function's args into a tool_args object.
+     * Default: `(...args) => ({ args })` — wraps all positional args under
+     * a single `args` key. Provide a custom mapper for cleaner audit trails.
+     */
+    toolArgs?: (...args: TArgs) => Record<string, unknown>;
+    /** Max ms to poll for the approval to resolve. Throws on timeout. */
+    timeoutMs?: number;
+    /** Ms between GET /approvals/:id polls. */
+    pollIntervalMs?: number;
+    /** Reuse an existing PliuzClient. Default: `new PliuzClient()`. */
+    client?: PliuzClient;
+    /** Optional context for the human approver. */
+    contextMessages?: readonly string[];
+    /** Optional session id (groups related approvals in the UI). */
+    sessionId?: string;
+    /** Optional originator (default: { type: 'system' }). */
+    originator?: Originator;
+}
+/**
+ * Wrap a function so every call is gated by Pliuz.
+ *
+ * The returned function ALWAYS returns a Promise, even if the input is sync.
+ * This is intentional — gating necessarily involves async HTTP calls.
+ */
+declare function gated<TArgs extends readonly unknown[], TResult>(options: GatedOptions<TArgs>, fn: (...args: TArgs) => Promise<TResult> | TResult): (...args: TArgs) => Promise<TResult>;
+
+export { DEFAULT_GATED_POLL_INTERVAL_MS, DEFAULT_GATED_TIMEOUT_MS, type GatedOptions, Originator, PliuzApiError, PliuzApprovalExpiredError, PliuzApprovalTimeoutError, PliuzAuthError, PliuzClient, PliuzConflictError, PliuzError, PliuzForbiddenError, PliuzNetworkError, PliuzNotFoundError, PliuzPolicyError, PliuzRateLimitError, PliuzRejectedError, PliuzServerError, PliuzTimeoutError, PliuzValidationError, REDACTED_PLACEHOLDER, VERSION, applyRedaction, errorForStatus, gated };