@sprigr/apps-app-sdk 0.10.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

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.
  *
@@ -2159,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;
@@ -1167,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,
@@ -1189,6 +1390,7 @@ export {
   buildMarketplaceWebhookUrl,
   bytesToBase64,
   canEmit,
+  canLog,
   checkConfirmationPolicy,
   commonDestructiveVerbs,
   constantTimeEqual,
@@ -1211,6 +1413,7 @@ export {
   isNotConnectedError,
   isStagingHost,
   listAppFiles,
+  logToPlatform,
   manifestIsFresh,
   offerUndo,
   overlaySprigr,
@@ -1235,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.10.0",
+  "version": "0.10.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",