@sprigr/apps-app-sdk 0.9.0 → 0.10.1

package/README.md

@@ -14,7 +14,8 @@ The runtime injects the `env.SPRIGR` host object **only on `/__sprigr/*` dispatc
 - `createMarketplaceEmitter(integrationType, defaults?)` — pre-bind an app's integration type so call sites pass only what varies; `sourceIntegration` is built per call from `env.INSTALL_ID`.
 - `canEmit(env)` — whether an emit could reach the platform by either transport. Gate work that only exists to feed an emit on this, not on `env.SPRIGR?.emit`.
 - `withSprigrEmitFallback(env)` — repair `env.SPRIGR.emit` once and leave existing call sites untouched. Matches the host object's contract (resolves `{ ok, eventId, queued }`, throws on non-2xx).
-- `resolveInstallBridge(env)` / `installTokenPost(bridge, path, body, opts?)` — build your own `/internal/wfp/*` fallback (collections, files, inbox) with the auth and error extraction handled.
+- `logToPlatform(env, entry | entry[], opts?)`: durable app logging from either context (`env.SPRIGR.log` on dispatch, `POST ${SPRIGR_PLATFORM_BASE}/internal/wfp/log` from an inline route). Rows land in the platform's `system_logs` Analytics Engine dataset (90-day retention, scoped to the install's company, category prefixed with the app slug), so use it instead of a per-webhook or per-tick audit row in your D1: D1 bills every row written, AE does not. Validation throws synchronously on a cap violation (summary 256, detail 4096, metadata JSON 3840, category 64 matching `[A-Za-z0-9._:-]`, 50 entries per call; nothing is ever truncated); after that the promise never rejects and resolves `{ ok: true, written }` or `{ ok: false, error, status?, detail? }`. Pass `{ waitUntil: ctx.waitUntil.bind(ctx) }` on an inline route so the send outlives the response. `withSprigrLogFallback(env, opts?)` installs `env.SPRIGR.log` once for many call sites; `canLog(env)` gates work whose only purpose is a log row; the `SprigrLogEntry` / `SprigrLogFn` types let your env interface declare the host member.
+- `resolveInstallBridge(env)` / `installTokenPost(bridge, path, body, opts?)`: build your own `/internal/wfp/*` fallback (collections, files, inbox) with the auth and error extraction handled. A non-2xx throws an `Error` whose `.status`, `.error` (the platform's code) and `.detail` are set alongside the message.
 - `overlaySprigr(env, sprigr)` — overlay a patched `SPRIGR` via `Object.create`. Never rebuild a dispatch-path env by spread: the real bindings live on the prototype and `SPRIGR` is non-enumerable, so `{ ...env }` yields an env whose `DB` is `undefined`.
 
 ## Per-actor tool wrappers
@@ -69,6 +70,7 @@ Three platform tiers, and they are not substitutes for each other. Full guide: [
 
 - `requireApproval(handlers, specs, opts)` wraps the named tools so each returns an `_approval` card instead of writing, then on the granted pass captures a before-image through the **pinned** connection and offers `_undo`. It resolves the connection inside itself, before the label lookup, the hash and the capture: a gate that sits outside the app's own pin names the wrong store, hashes the wrong store and captures the wrong store's copy. Register the result after the originals: `Object.assign(registry, requireApproval(registry, SPECS, opts))`.
 - `dispatcherApproval(specs, opts)`: the same gate for a one-tool-many-actions dispatcher. Build it beside the action registry and call `gate.run(action, args, env, () => def.execute(state, parsed))` from the dispatcher; params are read from `opts.inputField` (default `input`), the action name is hashed in, and `pinEnv` may return a per-actor token state rather than the env.
+- Every resolver on the gate is a **default, overridable per spec**: `ApprovalSpec.resolveConnection`, `.describeTarget` and `.stampConnection` win over the gate's for that spec alone. Reach for it when one app has two families of write that reach a connection differently (creates that POST under an account, deletes that address a global object id on a path carrying no account). One gate-level rule has to pick one of them, and for the other it prints a false connection on the card a person taps and mixes it into the grant hash. A spec that hits no connection returns `''`.
 - `approvalHash(rawId, connection, ...parts)`, `set(values)`, `seq(values)`: a stable operation identity so a tap survives the model reordering a list or dropping an optional argument on the retry.
 - `undoEnvelope({...})` throws on a blank field. The platform drops the whole envelope on a blank and mints nothing, silently.
 - `refuseWithoutForce(name, handler, opts)` / `archiveOfferRefusal(...)`: a delete refuses once and offers the vendor's native archive unless `force: true`.

package/dist/index.d.ts

@@ -465,6 +465,190 @@ declare function createMarketplaceEmitter<E extends WfpBridgeEnv = WfpBridgeEnv>
  */
 declare function withSprigrEmitFallback<E extends WfpBridgeEnv & object>(env: E): E;
 
+/**
+ * `env.SPRIGR.log`: durable app logging without a D1 audit table.
+ *
+ * The platform (sprigr-team#7154) exposes `env.SPRIGR.log(entry | entry[])`
+ * on every `/__sprigr/*` dispatch path. Each entry becomes one row in the
+ * platform's `system_logs` Analytics Engine dataset: 90-day retention,
+ * scoped to the install's company, `source = 'install'`, category prefixed
+ * with the app slug, metadata stamped with `app_slug` + `install_id`.
+ *
+ * Use it for every "we saw X" line a webhook, schedule tick, poll or tool
+ * call used to write into the app's own D1 as an audit row. D1 bills each
+ * row written (plus one per index), so a row per delivery is the largest
+ * D1 line item an app can produce (sprigr-apps#1519: one Shopify install
+ * wrote ~1.7M audit + dedup rows a day). AE has no per-row write bill.
+ *
+ * This module carries three things:
+ *
+ *   1. The TYPES of the host member (`SprigrLogEntry`, `SprigrLogFn`), so an
+ *      app's env interface can declare `log` on its `SPRIGR` type.
+ *   2. `validateLogEntries`, a byte-for-byte mirror of the caps the host
+ *      member and the platform route enforce. Caps are REJECTIONS, never
+ *      truncation: an oversize entry throws before anything is sent.
+ *   3. The inline-route fallback (`logToPlatform`, `withSprigrLogFallback`).
+ *      Inline Next.js route handlers never receive `env.SPRIGR`, so an app
+ *      whose provider webhook lands on one has no `log` there. Same escape
+ *      hatch as `emitMarketplaceEvent`: `POST ${SPRIGR_PLATFORM_BASE}/internal/wfp/log`
+ *      with the `SPRIGR_INSTALL_TOKEN` bearer and `{ entries: [...] }`.
+ *
+ * Wire contract (workers/provisioning/src/wfp-log.ts in sprigr-team):
+ *   200 { ok: true, written }
+ *   400 { error, detail, index, field, max?, length? } with error one of
+ *       summary_too_long, detail_too_long, metadata_too_large,
+ *       too_many_entries, invalid_category, invalid_level, ...
+ *   413 body_too_large (over 512 KiB)
+ *   401 / 404 bad token / inactive install
+ */
+
+/** Severity of one log row. Maps onto `system_logs.level`. */
+type SprigrLogLevel = 'debug' | 'info' | 'warn' | 'error';
+declare const SPRIGR_LOG_LEVELS: readonly SprigrLogLevel[];
+/**
+ * One row for `env.SPRIGR.log`. Every string cap is enforced client-side
+ * (throw) AND platform-side (400); nothing is ever truncated.
+ */
+interface SprigrLogEntry {
+    /** Required. */
+    level: SprigrLogLevel;
+    /**
+     * Required. 1-64 chars of `[A-Za-z0-9._:-]`, first char alphanumeric. The
+     * platform stores it as `<app_slug>.<category>` and it is the exact-match
+     * filter key when reading rows back, so make it a stable outcome name
+     * (`webhook.ok`, `webhook.duplicate`, `sync.tick`) and put the varying
+     * parts (topic, ids) in `metadata`.
+     */
+    category: string;
+    /** Required. 1-256 chars. One line a human can scan in a log viewer. */
+    summary: string;
+    /** Optional, at most 4096 chars. Reserve it for error text; bulk goes in `metadata`. */
+    detail?: string;
+    /** Optional plain object whose `JSON.stringify` is at most 3840 chars.
+     *  The platform merges `{ app_slug, install_id }` over it (platform keys win). */
+    metadata?: Record<string, unknown>;
+    /** Optional, at most 128 chars. Defaults on the dispatch path to the
+     *  dispatching actor's agent id. */
+    agent_id?: string;
+    /** Optional, at most 128 chars. Defaults on the platform to the ambient request trace. */
+    trace_id?: string;
+}
+/**
+ * What `env.SPRIGR.log` resolves to. The promise NEVER rejects: transport
+ * and platform failures come back as `{ ok: false }` (and a console.warn).
+ * Only a cap or shape violation throws, synchronously, before sending.
+ */
+type SprigrLogResult = {
+    ok: true;
+    written: number;
+} | {
+    ok: false;
+    error: string;
+    status?: number;
+    detail?: string;
+};
+/**
+ * The host member's signature. Declare it on your app's `SPRIGR` env type:
+ *
+ *   interface MyEnv { SPRIGR?: { emit: ...; log?: SprigrLogFn } }
+ *
+ * Mark it optional: wrapper builds older than sprigr-team#7154 do not carry
+ * it, and `logToPlatform` degrades cleanly when it is absent.
+ */
+type SprigrLogFn = (input: SprigrLogEntry | SprigrLogEntry[]) => Promise<SprigrLogResult>;
+/**
+ * The caps, verbatim from the platform route (`WFP_LOG_*` in
+ * workers/provisioning/src/wfp-log.ts) and the wrapper's `log` member. The
+ * platform's 400 body echoes its live cap, so a mismatch here is
+ * self-describing rather than silent.
+ */
+declare const SPRIGR_LOG_LIMITS: Readonly<{
+    maxEntriesPerCall: 50;
+    maxCategoryChars: 64;
+    categoryPattern: RegExp;
+    maxSummaryChars: 256;
+    maxDetailChars: 4096;
+    /** 4096-char metadata blob minus the platform's 256-char reserve for
+     *  `app_slug` + `install_id`. */
+    maxMetadataChars: 3840;
+    maxIdChars: 128;
+}>;
+/** Same 5s ceiling as the emit fallback: a webhook ack matters more than a log row. */
+declare const DEFAULT_LOG_TIMEOUT_MS = 5000;
+/**
+ * Thrown by `validateLogEntries` (and therefore by `logToPlatform` and the
+ * fallback `log`) before anything is sent. Carries the same fields as the
+ * platform's 400 body so a caller can log or branch on them.
+ */
+declare class SprigrLogValidationError extends Error {
+    readonly index: number;
+    readonly field: string;
+    readonly max?: number;
+    readonly length?: number;
+    constructor(message: string, fields: {
+        index: number;
+        field: string;
+        max?: number;
+        length?: number;
+    });
+}
+/**
+ * Validate one entry against the platform caps. Returns a fresh, normalised
+ * copy (unknown keys dropped, `undefined` optionals omitted) or throws
+ * `SprigrLogValidationError`. Pure; `index` only labels the error.
+ */
+declare function validateLogEntry(raw: unknown, index?: number): SprigrLogEntry;
+/**
+ * Normalise `entry | entry[]` to a validated array, or throw. One bad entry
+ * rejects the whole batch, matching the platform's all-or-nothing write.
+ */
+declare function validateLogEntries(input: unknown): SprigrLogEntry[];
+interface LogToPlatformOptions {
+    /** Override the 5s ceiling on the HTTP fallback. */
+    timeoutMs?: number;
+    /**
+     * `ctx.waitUntil` from the route handler. On the HTTP fallback the row
+     * is only guaranteed to land if the fetch outlives the response, which
+     * on an inline route means registering it here. The injected host member
+     * does this on its own; the fallback cannot see `ctx`, so hand it over.
+     */
+    waitUntil?: (p: Promise<unknown>) => void;
+}
+/**
+ * Whether a log row could reach the platform at all, by either transport.
+ * Gate work whose only purpose is to build a log entry on this, not on
+ * `env.SPRIGR?.log`, which is absent on every inline route.
+ */
+declare function canLog(env: WfpBridgeEnv): boolean;
+/**
+ * Write log rows from any execution context.
+ *
+ * Prefers the injected `env.SPRIGR.log`; falls back to the install-token
+ * bridge when it is absent (an inline Next route). Validation runs first
+ * and THROWS on a cap or shape violation, exactly like the host member, so
+ * a bad entry is caught at the call site. Everything after validation is
+ * reported in the result, never raised: a webhook ack is never at risk.
+ *
+ *   await logToPlatform(env, {
+ *     level: 'info', category: 'webhook.ok', summary: 'orders/create 6699',
+ *     metadata: { topic: 'orders/create', resource_id: '6699' },
+ *   }, { waitUntil: ctx.waitUntil.bind(ctx) });
+ */
+declare function logToPlatform(env: WfpBridgeEnv, input: SprigrLogEntry | SprigrLogEntry[], opts?: LogToPlatformOptions): Promise<SprigrLogResult>;
+/**
+ * Return an env whose `SPRIGR.log` works even on an inline route, leaving
+ * existing `env.SPRIGR.log(...)` call sites untouched. Same shape as
+ * `withSprigrEmitFallback`, and composable with it:
+ *
+ *   const env = withSprigrLogFallback(withSprigrEmitFallback(rawEnv), { waitUntil });
+ *
+ * The installed `log` matches the host member's contract: it throws
+ * synchronously on a cap or shape violation and its promise never rejects.
+ * When the bindings are absent the env is returned as-is (`SPRIGR.log`
+ * stays undefined) so callers fail the same way they already do.
+ */
+declare function withSprigrLogFallback<E extends WfpBridgeEnv & object>(env: E, opts?: LogToPlatformOptions): E;
+
 /**
  * Caller identity stamped by the platform on agent-initiated WFP dispatches.
  *
@@ -1250,12 +1434,25 @@ declare function refuseWithoutForce<E>(deleteAction: string, inner: ToolHandler<
  *    `_undo` ON A NULL CAPTURE. A failed capture does not fail the write: the
  *    user asked for it and a human approved it. It degrades to no token.
  *
+ * Every resolver here is gate-level by default and overridable per spec:
+ * `ApprovalSpec.resolveConnection` / `.describeTarget` / `.stampConnection`
+ * win over the gate's for that spec alone. One rule cannot describe two
+ * families of write truthfully, and both consumers of the resolved value are
+ * safety surfaces (the card a person reads, and the grant hash).
+ *
  * Generalised from the Shopify app's `require-approval.ts`; the per-tool
  * questions stay in the app, because only the app knows what cannot be walked
  * back.
  */
-/** Per-tool (or per-action) spec: how the card reads, and (optionally) how to journal a before-image. */
-interface ApprovalSpec<P = unknown> {
+/**
+ * Per-tool (or per-action) spec: how the card reads, and (optionally) how to
+ * journal a before-image.
+ *
+ * `P` is the pinned connection handed to `capture` / `describeTarget`; `E` is
+ * the env a spec-level `resolveConnection` receives. `E` defaults to `unknown`
+ * so `ApprovalSpec<MyState>` keeps working unchanged.
+ */
+interface ApprovalSpec<P = unknown, E = unknown> {
     /**
      * Arg names that may carry the target id, most specific first. ONE list, used
      * for both the card label and the grant hash, so the two cannot drift apart
@@ -1284,6 +1481,27 @@ interface ApprovalSpec<P = unknown> {
      * can ever cover it, which is the safe side but not the useful one.
      */
     count?: (args: ToolArgs) => number;
+    /**
+     * Overrides the gate's `resolveConnection` for THIS spec only; the gate's
+     * value stays the default for every spec that omits it.
+     *
+     * One gate serves every spec, so a gate-level resolver has to pick one rule.
+     * That is wrong the moment an app has two families of write that reach a
+     * connection differently: in meta-ads (sprigr-apps#1462) six creates POST
+     * under an ad account and three address a Graph object by id on a path that
+     * carries no account at all, so the account resolved for the creates was
+     * printed on the delete's card and mixed into its hash while being false.
+     * A resolver returning '' here is the honest answer for such a spec.
+     */
+    resolveConnection?: (env: E, args: ToolArgs) => Promise<string>;
+    /** Overrides the gate's `describeTarget` for this spec only. */
+    describeTarget?: (pinned: P, id: string, name: string) => Promise<string>;
+    /**
+     * Overrides the gate's `stampConnection` for this spec only. The stamp
+     * repeats the card's claim in the agent's "done" report, so a spec that
+     * resolves its own connection usually wants to stamp it its own way too.
+     */
+    stampConnection?: (result: unknown, connection: string) => unknown;
     /** Present only for tools whose write can be (partly) reversed. */
     undo?: UndoCaptureSpec<P>;
 }
@@ -1322,6 +1540,10 @@ interface ApprovalGateOptions<E, P = E> {
      * arguments and the install, canonicalised (a label like "EU store" becomes
      * the real domain). Return '' for a single-connection app. Never read it off
      * the arguments alone: on the retry the model usually omits it.
+     *
+     * This is the DEFAULT for every spec. A spec whose write reaches a
+     * connection by another rule overrides it with
+     * `ApprovalSpec.resolveConnection`.
      */
     resolveConnection: (env: E, args: ToolArgs) => Promise<string>;
     /**
@@ -1334,7 +1556,8 @@ interface ApprovalGateOptions<E, P = E> {
      * back to the id on any miss; never guess, a confidently wrong card is worse
      * than a terse one. Omit to always show the raw id. `name` is the tool, or
      * for a dispatcher the action, so a lookup can route by resource type when
-     * the id alone does not say what it is (an Asana gid).
+     * the id alone does not say what it is (an Asana gid). Overridable per
+     * spec.
      */
     describeTarget?: (pinned: P, id: string, name: string) => Promise<string>;
     /**
@@ -1345,7 +1568,8 @@ interface ApprovalGateOptions<E, P = E> {
     journal?: (env: E) => CaptureJournal;
     /**
      * Stamp the resolved connection onto a successful result (e.g. `{ store }`)
-     * so an agent reporting "deleted it" can name where. Optional.
+     * so an agent reporting "deleted it" can name where. Optional, and
+     * overridable per spec.
      */
     stampConnection?: (result: unknown, connection: string) => unknown;
 }
@@ -1382,7 +1606,7 @@ interface DispatcherApprovalGate<E> {
  * rename that quietly ungated a permanent delete is exactly the failure this
  * guard exists to prevent, and it would look identical to working.
  */
-declare function requireApproval<E>(handlers: Record<string, ToolHandler<E>>, specs: Record<string, ApprovalSpec<E>>, opts: RequireApprovalOptions<E>): Record<string, ToolHandler<E>>;
+declare function requireApproval<E>(handlers: Record<string, ToolHandler<E>>, specs: Record<string, ApprovalSpec<E, E>>, opts: RequireApprovalOptions<E>): Record<string, ToolHandler<E>>;
 /**
  * The same gate for a dispatcher tool (one tool, many actions selected by an
  * input field). Build it once beside the action registry and call `run` from
@@ -1396,7 +1620,7 @@ declare function requireApproval<E>(handlers: Record<string, ToolHandler<E>>, sp
  * params are read from `opts.inputField` (default `input`), or from the
  * top-level args when that field is absent (the flat-verb envelope).
  */
-declare function dispatcherApproval<E, P = E>(specs: Record<string, ApprovalSpec<P>>, opts: DispatcherApprovalOptions<E, P>): DispatcherApprovalGate<E>;
+declare function dispatcherApproval<E, P = E>(specs: Record<string, ApprovalSpec<P, E>>, opts: DispatcherApprovalOptions<E, P>): DispatcherApprovalGate<E>;
 
 /**
  * The reversal entry point every adopting app declares as `undo.reverse_tool`.
@@ -2119,4 +2343,4 @@ interface ExecutionContextLike {
 }
 type HandlerFn<TArgs, TResult> = (args: TArgs, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<TResult>;
 
-export { APPROVAL_GRANTED_KEY, type Actor, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DerivePolicyOptions, type DerivedPolicy, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type ResolveViewerOptions, type RestoreResult, type RestoreSpec, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, VIEWER_ANONYMOUS, VIEWER_CONTEXT_HEADER, VIEWER_PLATFORM_USER_ID_HEADER, VIEWER_ROLE_HEADER, VIEWER_USER_ID_HEADER, type VerbRule, type ViewerContext, type ViewerContextFailure, type ViewerContextVerification, type ViewerEnv, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, applyConfirmationPolicies, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, checkConfirmationPolicy, commonDestructiveVerbs, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, verifyViewerToken, withSprigrEmitFallback };
+export { APPROVAL_GRANTED_KEY, type Actor, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_LOG_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type DerivePolicyOptions, type DerivedPolicy, type DispatcherApprovalGate, type DispatcherApprovalOptions, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type LogToPlatformOptions, type ManifestDispatchBlock, type ManifestLike, type ManifestToolLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type ResolveViewerOptions, type RestoreResult, type RestoreSpec, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type SprigrLogEntry, type SprigrLogFn, type SprigrLogLevel, type SprigrLogResult, SprigrLogValidationError, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, VIEWER_ANONYMOUS, VIEWER_CONTEXT_HEADER, VIEWER_PLATFORM_USER_ID_HEADER, VIEWER_ROLE_HEADER, VIEWER_USER_ID_HEADER, type VerbRule, type ViewerContext, type ViewerContextFailure, type ViewerContextVerification, type ViewerEnv, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, applyConfirmationPolicies, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, canLog, checkConfirmationPolicy, commonDestructiveVerbs, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrLogFallback };

package/dist/index.js

@@ -245,8 +245,13 @@ async function installTokenPost(bridge, path, body, opts) {
       parsed = null;
     }
     if (!resp.ok) {
-      const detail = parsed && typeof parsed === "object" && "error" in parsed ? String(parsed.error) : text.slice(0, 200);
-      throw new Error(`${label} failed: ${resp.status} ${detail}`);
+      const obj = parsed && typeof parsed === "object" ? parsed : null;
+      const code = obj && "error" in obj ? String(obj.error) : text.slice(0, 200);
+      const err = new Error(`${label} failed: ${resp.status} ${code}`);
+      err.status = resp.status;
+      err.error = code;
+      if (obj && typeof obj.detail === "string") err.detail = obj.detail;
+      throw err;
     }
     return parsed ?? {};
   } finally {
@@ -312,6 +317,198 @@ function withSprigrEmitFallback(env) {
   return overlaySprigr(env, { ...existing, emit });
 }
 
+// src/platform-log.ts
+var SPRIGR_LOG_LEVELS = ["debug", "info", "warn", "error"];
+var SPRIGR_LOG_LIMITS = Object.freeze({
+  maxEntriesPerCall: 50,
+  maxCategoryChars: 64,
+  categoryPattern: /^[A-Za-z0-9][A-Za-z0-9._:-]*$/,
+  maxSummaryChars: 256,
+  maxDetailChars: 4096,
+  /** 4096-char metadata blob minus the platform's 256-char reserve for
+   *  `app_slug` + `install_id`. */
+  maxMetadataChars: 3840,
+  maxIdChars: 128
+});
+var DEFAULT_LOG_TIMEOUT_MS = 5e3;
+var SprigrLogValidationError = class extends Error {
+  index;
+  field;
+  max;
+  length;
+  constructor(message, fields) {
+    super(message);
+    this.name = "SprigrLogValidationError";
+    this.index = fields.index;
+    this.field = fields.field;
+    if (fields.max !== void 0) this.max = fields.max;
+    if (fields.length !== void 0) this.length = fields.length;
+  }
+};
+function isPlainObject(v) {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function tooLong(index, field, length, max) {
+  return new SprigrLogValidationError(
+    `env.SPRIGR.log: entries[${index}].${field} is ${length} chars; max ${max}. Nothing was sent; the platform never truncates a log field. Move the long part into detail or metadata, or split it across rows.`,
+    { index, field, max, length }
+  );
+}
+function validateLogEntry(raw, index = 0) {
+  const at = `env.SPRIGR.log: entries[${index}]`;
+  if (!isPlainObject(raw)) {
+    throw new SprigrLogValidationError(`${at} must be an object`, { index, field: "entry" });
+  }
+  const L = SPRIGR_LOG_LIMITS;
+  const level = raw.level;
+  if (typeof level !== "string" || !SPRIGR_LOG_LEVELS.includes(level)) {
+    throw new SprigrLogValidationError(`${at}.level must be one of ${SPRIGR_LOG_LEVELS.join(" | ")}`, {
+      index,
+      field: "level"
+    });
+  }
+  const category = raw.category;
+  if (typeof category !== "string" || category.length === 0) {
+    throw new SprigrLogValidationError(`${at}.category required (string)`, { index, field: "category" });
+  }
+  if (category.length > L.maxCategoryChars) throw tooLong(index, "category", category.length, L.maxCategoryChars);
+  if (!L.categoryPattern.test(category)) {
+    throw new SprigrLogValidationError(
+      `${at}.category must match ${L.categoryPattern} (letters, digits, . _ : -; no spaces)`,
+      { index, field: "category" }
+    );
+  }
+  const summary = raw.summary;
+  if (typeof summary !== "string" || summary.length === 0) {
+    throw new SprigrLogValidationError(`${at}.summary required (string)`, { index, field: "summary" });
+  }
+  if (summary.length > L.maxSummaryChars) throw tooLong(index, "summary", summary.length, L.maxSummaryChars);
+  const out = { level, category, summary };
+  if (raw.detail !== void 0) {
+    if (typeof raw.detail !== "string") {
+      throw new SprigrLogValidationError(`${at}.detail must be a string`, { index, field: "detail" });
+    }
+    if (raw.detail.length > L.maxDetailChars) throw tooLong(index, "detail", raw.detail.length, L.maxDetailChars);
+    out.detail = raw.detail;
+  }
+  if (raw.metadata !== void 0) {
+    if (!isPlainObject(raw.metadata)) {
+      throw new SprigrLogValidationError(`${at}.metadata must be a plain object`, { index, field: "metadata" });
+    }
+    const serialised = JSON.stringify(raw.metadata).length;
+    if (serialised > L.maxMetadataChars) {
+      throw new SprigrLogValidationError(
+        `${at}.metadata JSON is ${serialised} chars; max ${L.maxMetadataChars}. Nothing was sent; drop or split fields.`,
+        { index, field: "metadata", max: L.maxMetadataChars, length: serialised }
+      );
+    }
+    out.metadata = raw.metadata;
+  }
+  for (const field of ["agent_id", "trace_id"]) {
+    const v = raw[field];
+    if (v === void 0) continue;
+    if (typeof v !== "string" || v.length === 0 || v.length > L.maxIdChars) {
+      throw new SprigrLogValidationError(
+        `${at}.${field} must be a non-empty string of at most ${L.maxIdChars} chars`,
+        { index, field, max: L.maxIdChars, length: typeof v === "string" ? v.length : void 0 }
+      );
+    }
+    out[field] = v;
+  }
+  return out;
+}
+function validateLogEntries(input) {
+  const list = Array.isArray(input) ? input : [input];
+  if (list.length === 0) {
+    throw new SprigrLogValidationError("env.SPRIGR.log: at least one entry required", {
+      index: 0,
+      field: "entries"
+    });
+  }
+  if (list.length > SPRIGR_LOG_LIMITS.maxEntriesPerCall) {
+    throw new SprigrLogValidationError(
+      `env.SPRIGR.log: at most ${SPRIGR_LOG_LIMITS.maxEntriesPerCall} entries per call (got ${list.length}); nothing was sent`,
+      {
+        index: 0,
+        field: "entries",
+        max: SPRIGR_LOG_LIMITS.maxEntriesPerCall,
+        length: list.length
+      }
+    );
+  }
+  return list.map((e, i) => validateLogEntry(e, i));
+}
+function bindingLog(env) {
+  const sprigr = env.SPRIGR;
+  return typeof sprigr?.log === "function" ? sprigr.log.bind(sprigr) : null;
+}
+function canLog(env) {
+  return bindingLog(env) !== null || resolveInstallBridge(env) !== null;
+}
+async function postLog(env, entries, timeoutMs) {
+  const bridge = resolveInstallBridge(env);
+  if (!bridge) {
+    return { ok: false, error: "no_log_path", detail: describeMissingBridge(env) };
+  }
+  try {
+    const reply = await installTokenPost(bridge, "/internal/wfp/log", { entries }, {
+      label: "log",
+      timeoutMs
+    });
+    if (reply.ok === false) {
+      return { ok: false, error: reply.error ?? "log_failed", detail: reply.detail };
+    }
+    return { ok: true, written: typeof reply.written === "number" ? reply.written : entries.length };
+  } catch (err) {
+    const e = err;
+    const message = e instanceof Error ? e.message : String(err);
+    console.warn(`[sprigr-log] log fallback failed: ${message}`);
+    return {
+      ok: false,
+      error: e.error ?? (e.status !== void 0 ? "log_failed" : "log_transport_failed"),
+      ...e.status !== void 0 ? { status: e.status } : {},
+      detail: e.detail ?? message
+    };
+  }
+}
+function logToPlatform(env, input, opts) {
+  const entries = validateLogEntries(input);
+  const injected = bindingLog(env);
+  let result;
+  if (injected) {
+    try {
+      result = Promise.resolve(injected(entries)).catch((err) => ({
+        ok: false,
+        error: "log_failed",
+        detail: err instanceof Error ? err.message : String(err)
+      }));
+    } catch (err) {
+      result = Promise.resolve({
+        ok: false,
+        error: "log_failed",
+        detail: err instanceof Error ? err.message : String(err)
+      });
+    }
+  } else {
+    result = postLog(env, entries, opts?.timeoutMs ?? DEFAULT_LOG_TIMEOUT_MS);
+  }
+  if (opts?.waitUntil) opts.waitUntil(result);
+  return result;
+}
+function withSprigrLogFallback(env, opts) {
+  if (bindingLog(env)) return env;
+  const bridge = resolveInstallBridge(env);
+  if (!bridge) return env;
+  const log = (input) => {
+    const entries = validateLogEntries(input);
+    const p = postLog(env, entries, opts?.timeoutMs ?? DEFAULT_LOG_TIMEOUT_MS);
+    if (opts?.waitUntil) opts.waitUntil(p);
+    return p;
+  };
+  const existing = env.SPRIGR ?? {};
+  return overlaySprigr(env, { ...existing, log });
+}
+
 // src/actor.ts
 function parseActor(args) {
   if (!args || typeof args !== "object") return void 0;
@@ -758,10 +955,11 @@ async function pin(opts, env, connection) {
   return opts.pinEnv(env, connection);
 }
 async function askPass(name, spec, params, env, opts, hashPrefix) {
-  const connection = await opts.resolveConnection(env, params);
+  const connection = await (spec.resolveConnection ?? opts.resolveConnection)(env, params);
   const rawId = rawIdOf(params, spec.keys);
   const pinned = await pin(opts, env, connection);
-  const target = rawId && opts.describeTarget ? await safeLabel(opts.describeTarget, pinned, rawId, name) : rawId || "(unknown id)";
+  const describeTarget = spec.describeTarget ?? opts.describeTarget;
+  const target = rawId && describeTarget ? await safeLabel(describeTarget, pinned, rawId, name) : rawId || "(unknown id)";
   const extra = spec.hash ? spec.hash(params) : [];
   const count = countOf(spec, params, rawId);
   return {
@@ -774,8 +972,9 @@ async function askPass(name, spec, params, env, opts, hashPrefix) {
   };
 }
 async function grantedPass(name, spec, params, env, opts, write) {
-  const connection = await opts.resolveConnection(env, params);
-  const stamp = (r) => connection && opts.stampConnection ? opts.stampConnection(r, connection) : r;
+  const connection = await (spec.resolveConnection ?? opts.resolveConnection)(env, params);
+  const stampConnection = spec.stampConnection ?? opts.stampConnection;
+  const stamp = (r) => connection && stampConnection ? stampConnection(r, connection) : r;
   const undo = spec.undo;
   const id = rawIdOf(params, spec.keys);
   if (!undo || !id) return stamp(await write());
@@ -1165,11 +1364,15 @@ function commonDestructiveVerbs(subject) {
 export {
   APPROVAL_GRANTED_KEY,
   DEFAULT_EMIT_TIMEOUT_MS,
+  DEFAULT_LOG_TIMEOUT_MS,
   DEFAULT_MAX_FILE_BYTES,
   DEFAULT_MONEY_FIELDS,
   DEFAULT_WRITE_PREFIXES,
   InvalidUndoEnvelopeError,
   NotConnectedError,
+  SPRIGR_LOG_LEVELS,
+  SPRIGR_LOG_LIMITS,
+  SprigrLogValidationError,
   UNIT_SEP,
   VIEWER_ANONYMOUS,
   VIEWER_CONTEXT_HEADER,
@@ -1187,6 +1390,7 @@ export {
   buildMarketplaceWebhookUrl,
   bytesToBase64,
   canEmit,
+  canLog,
   checkConfirmationPolicy,
   commonDestructiveVerbs,
   constantTimeEqual,
@@ -1209,6 +1413,7 @@ export {
   isNotConnectedError,
   isStagingHost,
   listAppFiles,
+  logToPlatform,
   manifestIsFresh,
   offerUndo,
   overlaySprigr,
@@ -1233,6 +1438,9 @@ export {
   set,
   tool,
   undoEnvelope,
+  validateLogEntries,
+  validateLogEntry,
   verifyViewerToken,
-  withSprigrEmitFallback
+  withSprigrEmitFallback,
+  withSprigrLogFallback
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprigr/apps-app-sdk",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",