@1claw/sdk 0.59.10 → 0.61.0

package/dist/types.d.ts

@@ -1333,13 +1333,61 @@ export interface ApprovalRequest {
     created_at: string;
 }
 export interface CreateApprovalRequest {
+    /**
+     * A control-plane request (`access_request`, `policy_request`,
+     * `binding_request`) or a business action named `namespace.verb`
+     * (`refund.create`, `social.post`).
+     *
+     * Actions 1Claw executes on approval — `card_order`, `agent_transaction`
+     * and friends — are created by the platform and rejected here.
+     */
     action: string;
     target_type: string;
     target_id: string;
+    /** What the human is shown: `{ title, body, fields }`. */
     summary: Record<string, unknown>;
+    /**
+     * What the action will actually do. The enforced risk tier and the
+     * plain-language line are derived from this, not from `summary`.
+     */
+    payload?: Record<string, unknown>;
     reason?: string;
+    /**
+     * Advisory. The server derives the enforced tier and takes the higher of
+     * the two — a caller may raise its own bar, never lower it. The response
+     * returns both.
+     */
+    declared_risk_tier?: number;
+    /** @deprecated Renamed to `declared_risk_tier`. Still accepted. */
     risk_tier?: number;
 }
+/** An approval as returned by the API. */
+export interface Approval {
+    id: string;
+    org_id: string;
+    user_id: string;
+    agent_id: string | null;
+    action: string;
+    target_type: string;
+    target_id: string;
+    /** The tier actually enforced. Authoritative. */
+    risk_tier: number;
+    /** What the caller asked for, when it asked for anything. */
+    declared_risk_tier?: number | null;
+    /** The caller asked for a lower tier than policy required. */
+    declared_below_floor?: boolean;
+    status: "pending" | "approved" | "rejected";
+    summary: Record<string, unknown>;
+    /** Plain-language line, rendered server-side from the agent's policy template. */
+    human_summary?: string | null;
+    payload?: Record<string, unknown>;
+    reason: string | null;
+    decision_reason: string | null;
+    decided_by: string | null;
+    decided_at: string | null;
+    expires_at: string | null;
+    created_at: string;
+}
 export interface ApprovalListResponse {
     approvals: ApprovalRequest[];
 }
@@ -1458,11 +1506,155 @@ export interface TemplateResponse {
     name: string;
     description: string;
     version: number;
+    /**
+     * SHA-256 of `spec`. Lets a caller tell a version bump that changed nothing
+     * from one that did. Null on templates written before migration 245.
+     */
+    spec_hash?: string | null;
     spec: Record<string, unknown>;
     is_active: boolean;
     created_at: string;
     updated_at: string;
 }
+/** How a cohort splits across the template versions it was provisioned from. */
+export interface FleetVersionBucket {
+    template_version: number | null;
+    agents: number;
+}
+export interface FleetSummaryResponse {
+    template_id: string;
+    template_name: string;
+    current_version: number;
+    spec_hash?: string | null;
+    total_agents: number;
+    version_skew: FleetVersionBucket[];
+    agents_on_current_version: number;
+    agents_behind: number;
+    /** Agents a previous rollout declined to touch. */
+    drifted_agents: number;
+    /**
+     * The fields `bulkPatch` and `rollout` will carry.
+     *
+     * Read this rather than hard-coding the list. It is deliberately narrower
+     * than a single-agent patch — no guardrails, no capability flags — because
+     * a fleet request applies to every agent at once and nobody reviews it per
+     * agent. It may narrow further.
+     */
+    bulk_patchable_fields: string[];
+}
+export interface FleetAgent {
+    agent_id: string;
+    name: string;
+    org_id: string;
+    platform_connection_id?: string | null;
+    provisioned_from_version?: number | null;
+    last_fleet_sync_at?: string | null;
+    /**
+     * Fields a rollout skipped because they were changed outside fleet control.
+     * The standing answer to "why is this agent behind?".
+     */
+    drift_fields: string[];
+    is_active: boolean;
+    is_current: boolean;
+}
+export interface ListFleetAgentsResponse {
+    agents: FleetAgent[];
+    limit: number;
+    offset: number;
+    current_version: number;
+}
+export interface BulkPatchFleetResponse {
+    fields_applied: string[];
+    agents_matched: number;
+    agents_updated: number;
+}
+export type FleetRolloutOutcome = {
+    outcome: "already_current";
+    agent_id: string;
+} | {
+    outcome: "synced";
+    agent_id: string;
+    fields: string[];
+} | {
+    outcome: "skipped_drifted";
+    agent_id: string;
+    drift_fields: string[];
+};
+export interface FleetRolloutResponse {
+    /** Null for a dry run, which claims no job. */
+    job_id: string | null;
+    to_version: number;
+    dry_run: boolean;
+    forced: boolean;
+    total_agents: number;
+    synced: number;
+    already_current: number;
+    skipped_drifted: number;
+    outcomes: FleetRolloutOutcome[];
+}
+export interface FleetRolloutRequest {
+    /** Overwrite hand edits. Still cannot carry a guardrail. */
+    force?: boolean;
+    /** Report the plan without applying it. Claims no job. */
+    dry_run?: boolean;
+}
+export interface PauseFleetResponse {
+    agents_paused: number;
+}
+/**
+ * Text the server judged suspicious but not blocking.
+ *
+ * Returned instead of a bare string so a caller cannot pass it to a model by
+ * accident: the type will not typecheck as a string. Treat `raw_text` as data
+ * and prepend `system_prefix` if it must reach a prompt at all.
+ */
+export interface UntrustedContent {
+    untrusted_content: true;
+    source: string;
+    id: string;
+    field: string;
+    raw_text: string;
+    system_prefix: string;
+}
+/** A string when clean, an envelope when `content_warning` is true. */
+export type MaybeUntrusted = string | UntrustedContent;
+export interface DirectoryJob {
+    id: string;
+    title: MaybeUntrusted;
+    description: MaybeUntrusted;
+    tags: string[];
+    required_capabilities: string[];
+    budget?: {
+        amount: string;
+        currency: string;
+    } | null;
+    deadline_at?: string | null;
+    status: "open" | "awarded" | "completed" | "cancelled" | "expired";
+    bid_count: number;
+    content_warning: boolean;
+    awarded_agent_id?: string | null;
+    a2a_handoff?: Record<string, unknown> | null;
+    expires_at: string;
+    created_at: string;
+}
+export interface DirectoryJobBid {
+    id: string;
+    job_id: string;
+    bidder_agent_id: string;
+    summary: MaybeUntrusted;
+    proposed_cost?: {
+        amount: string;
+        currency: string;
+    } | null;
+    estimated_duration_mins?: number | null;
+    status: "pending" | "accepted" | "rejected" | "withdrawn";
+    content_warning: boolean;
+    created_at: string;
+}
+/** Narrow a possibly-wrapped field, and say plainly whether it was flagged. */
+export declare function isUntrusted(v: MaybeUntrusted): v is UntrustedContent;
+/** The text of a field, wrapped or not. Never pass this straight to a model. */
+export declare function rawText(v: MaybeUntrusted): string;
 export interface TemplateListResponse {
     templates: TemplateResponse[];
 }
@@ -2548,4 +2740,289 @@ export interface ShamirSetupResponse {
     custody_mode: string;
     created_at: string;
 }
+export interface ConnectorPreset {
+    slug: string;
+    display_name: string;
+    description: string;
+    category: string;
+    /** `oauth_providers.slug`, or null when the connector uses a pasted API key. */
+    provider_slug: string | null;
+    oauth_scopes: string[];
+    /** Scopes without which the connector cannot do anything. */
+    required_scopes: string[];
+    binding_type: string;
+    base_url: string;
+    /** Hosts the installed binding may reach. Always includes the base URL's host. */
+    allowed_hosts: string[];
+    documentation_url: string;
+    tier_required: string;
+    requires_oauth: boolean;
+}
+export interface ConnectorPresetListResponse {
+    presets: ConnectorPreset[];
+}
+export interface InstallConnectorRequest {
+    /** Defaults to the preset slug. */
+    binding_name?: string;
+    /** May narrow the preset's scopes; never extend them. */
+    scopes?: string[];
+    redirect_after?: string;
+}
+export interface InstallConnectorResponse {
+    binding_id: string;
+    binding_name: string;
+    preset_slug: string;
+    /** Absent for connectors that use a pasted API key rather than OAuth. */
+    authorization_url?: string | null;
+    /** What the user still has to do, in words. */
+    next_step: string;
+}
+export interface InstalledConnector {
+    binding_id: string;
+    binding_name: string;
+    preset_slug: string;
+    /** Null if the preset has since been retired from the catalogue. */
+    display_name?: string | null;
+    is_active: boolean;
+    /** The OAuth round trip completed and a token is stored. */
+    connected: boolean;
+    /** The stored token was rejected; the user must reconnect. */
+    needs_reauth: boolean;
+    created_at: string;
+}
+export interface InstalledConnectorListResponse {
+    connectors: InstalledConnector[];
+}
+export type NotificationTargetType = "sms" | "webhook" | "expo" | "email";
+export interface NotificationTarget {
+    id: string;
+    target_type: NotificationTargetType;
+    user_id?: string | null;
+    agent_id?: string | null;
+    /**
+     * `{ phone_number }` for sms (E.164 only), `{ url }` for webhook (https
+     * only), `{ email }`, or `{ push_token }`.
+     */
+    config: Record<string, unknown>;
+    /** Empty means every event. */
+    events: string[];
+    is_active: boolean;
+    /**
+     * An unverified SMS target receives notifications but cannot decide an
+     * approval by reply.
+     */
+    verified: boolean;
+    created_at: string;
+}
+export interface NotificationTargetListResponse {
+    targets: NotificationTarget[];
+}
+export interface CreateNotificationTargetRequest {
+    target_type: NotificationTargetType;
+    config: Record<string, unknown>;
+    events?: string[];
+    /** The agent whose SMS channel sends to this target. */
+    agent_id?: string;
+    /** Defaults to the caller. */
+    user_id?: string;
+}
+export interface UsageCounts {
+    api_requests: number;
+    signatures: number;
+    execution_intents: number;
+    execution_intents_tee: number;
+    /** A decimal string. Money is not a float; zero is `"0"`. */
+    inference_usd: string;
+    credits_debited_cents: number;
+}
+export interface ConnectionUsageEntry {
+    connection_id: string;
+    usage: UsageCounts;
+}
+/**
+ * Usage that could not be charged to a connection.
+ *
+ * The two are different problems. `none` is ordinary traffic with no platform
+ * linkage. `ambiguous` belongs to a real end-user whose connection could not be
+ * determined — that is the one worth acting on.
+ */
+export interface UnattributedUsage {
+    ambiguous: UsageCounts;
+    none: UsageCounts;
+}
+export interface AppUsageReport {
+    app_id: string;
+    period_start: string;
+    /** Exclusive: the period is half-open. */
+    period_end: string;
+    connections: ConnectionUsageEntry[];
+    unattributed: UnattributedUsage;
+    /** Connections plus both unattributed buckets. Derived, not queried. */
+    totals: UsageCounts;
+    has_ambiguous_usage: boolean;
+}
+export interface Peer {
+    id: string;
+    peer_type: "user" | "platform_connection" | "external";
+    peer_ref: string;
+    display_name?: string | null;
+    profile: Record<string, unknown>;
+    /** Archived when a connection is disconnected: agents lose observation, the person keeps export and delete. */
+    status: "active" | "archived";
+    /** How many agents observe this peer. The list itself is not returned. */
+    observer_count: number;
+    created_at: string;
+}
+export interface PeerFact {
+    fact_key: string;
+    fact_value: Record<string, unknown>;
+    /** 0..1, capped below certainty — no history makes the next decision certain. */
+    confidence?: string | null;
+    /** Why this is believed. Entries are `event`, `tombstone` (the event expired) or `human`. */
+    provenance: unknown[];
+    /** A person corrected this; the processor will not overwrite it. */
+    edited_by_human: boolean;
+    updated_at: string;
+}
+export interface PeerWithFacts {
+    peer: Peer;
+    facts: PeerFact[];
+}
+export interface CreatePeerRequest {
+    peer_type: "user" | "platform_connection" | "external";
+    peer_ref: string;
+    display_name?: string;
+    platform_connection_id?: string;
+    /** Empty means nobody. A peer with no observers is readable by no agent. */
+    observer_agent_ids?: string[];
+}
+export interface PeerContextResponse {
+    /** Empty when nothing has been derived yet. */
+    context: string;
+    characters: number;
+    budget?: number;
+    facts_available?: number;
+}
+export interface PredictApprovalRequest {
+    action_type: string;
+    payload?: Record<string, unknown>;
+    /** The server-derived tier for this action. */
+    effective_risk_tier: number;
+}
+export type PredictApprovalBlockedReason = "no_matching_rule" | "rule_requires_approval" | "above_configured_threshold" | "risk_tier_requires_step_up" | "action_is_sensitive";
+export interface PredictApprovalResponse {
+    /** An observation about a person. Absent when there is no comparable history. */
+    likelihood?: number | null;
+    reasoning: string;
+    /**
+     * A statement about your policy — whether a rule you already wrote permits
+     * this automatically. Never derived from `likelihood`.
+     */
+    suggest_auto: boolean;
+    blocked_reason?: PredictApprovalBlockedReason;
+}
+export interface PayPrepareRequest {
+    /**
+     * The exact bytes the paywall served, base64. Send them verbatim: the digest
+     * a person authorizes is computed from this preimage, so any field parsed
+     * out and re-sent would fall outside what they actually approved.
+     */
+    challenge_b64: string;
+    method: string;
+    resource_url: string;
+    /** Reuse on retry so one 402 cannot become two payments. */
+    idempotency_key?: string;
+    /** A request, not an instruction — the vault decides (D12). */
+    mode?: "strict" | "session" | "auto";
+}
+export interface PayPrepareResponse {
+    session_id: string;
+    payment_digest: string;
+    sign_idempotency_key: string;
+    quote: Record<string, unknown>;
+    valid_before: string | null;
+    expires_at: string;
+    /** `allow` | `require_passkey` | `require_grant` | `deny: <reason>` */
+    authorization: string;
+    /** Under 30 seconds left — may expire while a person reads the page. */
+    short_window: boolean;
+}
+export interface PaySignRequest {
+    session_id: string;
+    mode?: "strict" | "session" | "auto";
+    /** Offer a specific grant; omit for the newest live one. */
+    grant_id?: string;
+}
+export interface PaySignResponse {
+    payment_id: string;
+    /** The `X-PAYMENT` header value. The signature, never the key. */
+    payment_header: string;
+    amount_usd: string;
+    pay_to: string;
+    grant_id: string | null;
+}
+export interface PayResultRequest {
+    http_status?: number;
+    /** Omit when the outcome is genuinely unknown rather than guessing false. */
+    settled?: boolean;
+    error?: string | null;
+}
+export interface CreatePayGrantRequest {
+    cap_usd: string;
+    ttl_secs: number;
+    /** `null`/omitted means any recipient; `[]` means none. */
+    allowed_paytos?: string[] | null;
+    /** The digest the person asserted over. */
+    grant_digest: string;
+}
+export interface PayGrantResponse {
+    grant_id: string;
+    cap_usd: string;
+    remaining_usd: string;
+    expires_at: string;
+    allowed_paytos: string[] | null;
+}
+export interface PaySessionResponse {
+    session_id: string;
+    agent_id: string;
+    agent_name: string;
+    status: string;
+    quote: Record<string, unknown>;
+    payment_digest: string;
+    valid_before: string | null;
+    expires_at: string;
+}
+export interface PaymentStatusResponse {
+    payment_id: string;
+    status: string;
+    amount_usd: string | null;
+    pay_to: string;
+    resource_url: string;
+    grant_id: string | null;
+}
+export interface UpdatePayGuardrailsRequest {
+    pay_enabled?: boolean;
+    pay_max_usd?: string | null;
+    pay_daily_limit_usd?: string | null;
+    /** Null is not a wildcard — for an unattended agent it means no one. */
+    pay_payto_allowlist?: string[] | null;
+    /** Defaults true. Turning it off is what "unattended" means. */
+    pay_require_passkey?: boolean;
+    pay_require_approval?: boolean;
+    pay_grant_mode_enabled?: boolean;
+    pay_grant_max_usd?: string | null;
+    pay_grant_max_ttl_secs?: number | null;
+}
+export interface PaySettingsResponse {
+    agent_id: string;
+    pay_enabled: boolean;
+    pay_max_usd: string | null;
+    pay_daily_limit_usd: string | null;
+    pay_payto_allowlist: string[] | null;
+    pay_require_passkey: boolean;
+    pay_require_approval: boolean;
+    pay_grant_mode_enabled: boolean;
+    pay_grant_max_usd: string | null;
+    pay_grant_max_ttl_secs: number | null;
+}
 //# sourceMappingURL=types.d.ts.map