@sprigr/apps-app-sdk 0.5.0 → 0.7.0

package/README.md

@@ -17,6 +17,31 @@ The runtime injects the `env.SPRIGR` host object **only on `/__sprigr/*` dispatc
 - `resolveInstallBridge(env)` / `installTokenPost(bridge, path, body, opts?)` — build your own `/internal/wfp/*` fallback (collections, files, inbox) with the auth and error extraction handled.
 - `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
+
+An agent-facing tool must resolve the **calling** identity's own credential, or refuse. It must never fall back to another connected account, not even for a read: an install is company-wide, but access is not.
+
+```ts
+// src/handlers/wrap.ts: bind the options once
+import { createToolWrappers, NotConnectedError } from '@sprigr/apps-app-sdk';
+
+export const { tool, actorTool } = createToolWrappers<MyEnv>({
+  notConnectedHint: 'Call my_connect and send the user the link.',
+  mapError: (err) =>
+    err instanceof MyApiError ? { error: err.message, status: err.status } : null,
+});
+
+// src/handlers/things.ts
+export default { list_things: actorTool(async (env, actor, args) => { /* ... */ }) };
+```
+
+- `actorTool(fn)`: reads the platform-stamped `args.actor`, returns `412 no_caller_identity` when it is absent, and maps a thrown `NotConnectedError` to `412 not_connected` with your connect hint. Identity comes only from the nested `args.actor`; flat body fields are agent-supplied and spoofable.
+- `tool(fn)`: for handlers with genuinely no caller (schedules, webhooks, platform mirrors). Those need a *designated service connection*, which is not licence for an agent-facing handler to borrow one.
+- `NotConnectedError`: throw from your token resolver when the **caller** has no connection. Don't throw it for "the install has none", which is a different fault with a different fix.
+- `isNotConnectedError(err)`: matches by class *and* by `name`, so it still works when the vendor pattern puts two copies of this module in one isolate and `instanceof` would silently fail.
+
+**Why this is in the SDK:** every app hand-rolled this, and one shipped a version that fell back to "the first connected actor on the install" when the caller had none. One person's consent then exposed their account to every agent on that install, in production.
+
 ## Webhook callback URLs
 
 - `resolvePlatformWebhookBase(env)` / `buildMarketplaceWebhookUrl(env, installId, topicPath)` — env-correct platform host, so a staging install never registers prod-pointing subscriptions.
@@ -26,7 +51,7 @@ The runtime injects the `env.SPRIGR` host object **only on `/__sprigr/*` dispatc
 - `fetchWithRetry` — rate-limit-header-aware, jittered retry
 - `constantTimeEqual(a, b)` — bearer-secret verification
 - `encodeState` / `decodeState` — OAuth state base64url
-- `parseActor` / `actorKey` — per-actor token scoping
+- `parseActor` / `actorKey` / `ownerFromActorKey` — per-actor token scoping
 - `putAppFile` / `putAppFileStream` / `appFileUrl` / `getAppFile` / `listAppFiles` / `deleteAppFile` — durable app-scoped file storage from outside the injected bridge
 - `fetchFileBytes` / `fetchFileAsBase64` / `bytesToBase64` / `base64ToBytes` — file byte helpers
 

package/dist/index.d.ts

@@ -582,6 +582,138 @@ interface InboxOwner {
  */
 declare function ownerFromActorKey(key: string | null | undefined): InboxOwner | null;
 
+/**
+ * Adapters between the marketplace wrapper's calling convention and an app's
+ * inner handler signatures, with fail-closed per-actor authorization built in.
+ *
+ * The wrapper calls `handler(args, env, ctx)`, args first. Inner handlers are
+ * usually written `(env, args)` or `(env, actor, args)`, so something has to
+ * flip them and shape thrown errors into a result an agent can read.
+ *
+ *   tool(fn)       actor-less handlers: schedules, webhooks, internal work.
+ *   actorTool(fn)  per-actor handlers: reads the platform-stamped
+ *                  `args.actor`, fails closed with 412 when it is absent, and
+ *                  maps NotConnectedError to a 412 `not_connected`.
+ *
+ * WHY THIS IS IN THE SDK. Every app hand-rolled this wrapper, and the gorgias
+ * app got it wrong in the way that matters: when the caller had no connection
+ * it fell through to "the first connected actor on the install", so one
+ * person's consent made their whole helpdesk readable and writable by every
+ * agent on a company-wide install. That reached production. The rule is not
+ * hard, but it is easy to write a plausible-looking fallback for, so the
+ * correct version belongs in one place that apps import rather than copy.
+ *
+ * THE RULE: an agent-facing tool resolves the CALLING identity's own
+ * credential, or refuses. Never another actor's, not even to be helpful, and
+ * not even for a read. Background paths (schedules, webhooks, platform
+ * mirrors) genuinely have no caller and need a designated service connection;
+ * that is what `tool()` is for, and it is not licence for an agent-facing
+ * handler to borrow one.
+ */
+
+/** What every wrapped handler returns. `ok:false` never throws past the wrapper. */
+type ToolResult<R> = {
+    ok: true;
+    result: R;
+} | {
+    ok: false;
+    error: string;
+    hint?: string;
+    status?: number;
+};
+/**
+ * Throw this from a token resolver when the CALLING actor has no connection
+ * of their own. `actorTool` turns it into a 412 `not_connected` carrying the
+ * app's connect hint, which is the agent's cue to mint an authorize link
+ * rather than retry.
+ *
+ * Do not throw it for "the install has no connection at all" on a background
+ * path: that is a different failure with a different fix (an admin
+ * designating a service connection), and collapsing the two sends the agent
+ * chasing a consent link it cannot complete.
+ */
+declare class NotConnectedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * True for a NotConnectedError, INCLUDING one thrown by a different copy of
+ * this module.
+ *
+ * `instanceof` alone is wrong here and would fail silently. Apps reach this
+ * package two ways: a normal npm dependency, and the legacy `sprigrVendor`
+ * mirror that copies the source into `src/lib/vendor/`. An app that vendors
+ * the SDK while a dependency resolves its own npm copy has TWO distinct
+ * `NotConnectedError` classes at runtime, and `instanceof` across them is
+ * false. The failure mode is the bad one: the error falls through to the
+ * generic branch, the agent gets an opaque message instead of `not_connected`,
+ * and never learns to offer a connect link. Matching on `name` as well costs
+ * nothing and survives the boundary.
+ */
+declare function isNotConnectedError(err: unknown): boolean;
+interface ToolWrapperOptions {
+    /**
+     * Hint returned alongside `not_connected`. Name the app's connect tool and
+     * frame it as a one-click authorization rather than an error, because this
+     * string is what the agent repeats to the user.
+     */
+    notConnectedHint?: string;
+    /**
+     * Hint returned alongside `no_caller_identity`.
+     */
+    noCallerIdentityHint?: string;
+    /**
+     * Shape an app-specific error (a provider API error carrying an HTTP
+     * status) into a result. Return null to fall through to the generic
+     * `{ error: message }`. Runs AFTER the not_connected check.
+     *
+     *   mapError: (err) => err instanceof GraphApiError
+     *     ? { error: err.message, status: err.status }
+     *     : null,
+     */
+    mapError?: (err: unknown) => {
+        error: string;
+        status?: number;
+        hint?: string;
+    } | null;
+}
+/**
+ * Wrap an actor-less handler. Catches throws into `{ ok: false, error }` so an
+ * agent caller never sees a bare exception.
+ */
+declare function tool<Env, A, R>(fn: (env: Env, args: A) => Promise<R>, opts?: ToolWrapperOptions): (args: A, env: Env) => Promise<ToolResult<R>>;
+/**
+ * Wrap a per-actor handler. Fails closed twice over: no stamped identity is
+ * `no_caller_identity`, and a caller with no connection of their own is
+ * `not_connected`. Both 412, both distinct on purpose: the first is a
+ * plumbing fault the agent should retry differently, the second the agent can
+ * resolve itself by sending the user a link.
+ *
+ * Identity comes ONLY from the nested, platform-stamped `args.actor`.
+ * `parseActor` deliberately ignores flat body fields, which are agent-supplied
+ * and spoofable; honouring one would let a caller name any colleague and act
+ * as them.
+ */
+declare function actorTool<Env, A, R>(fn: (env: Env, actor: Actor, args: A) => Promise<R>, opts?: ToolWrapperOptions): (args: A, env: Env) => Promise<ToolResult<R>>;
+/**
+ * Bind the options once and get both wrappers typed to the app's env, so
+ * handler files call `actorTool(fn)` with no per-call ceremony:
+ *
+ *   // src/handlers/wrap.ts
+ *   export const { tool, actorTool } = createToolWrappers<Ms365Env>({
+ *     notConnectedHint: 'Call ms_connect and send the user the link…',
+ *     mapError: (err) =>
+ *       err instanceof GraphApiError ? { error: err.message, status: err.status } : null,
+ *   });
+ *
+ * Options bound once is the point: an app that repeats them at each of fifty
+ * call sites will drift, and the one that drifts is the hint telling a user
+ * how to connect.
+ */
+declare function createToolWrappers<Env>(opts?: ToolWrapperOptions): {
+    tool: <A, R>(fn: (env: Env, args: A) => Promise<R>) => (args: A, env: Env) => Promise<ToolResult<R>>;
+    actorTool: <A, R>(fn: (env: Env, actor: Actor, args: A) => Promise<R>) => (args: A, env: Env) => Promise<ToolResult<R>>;
+};
+
 /**
  * App-scoped R2 file storage (platform feature, 2026-06).
  *
@@ -769,6 +901,56 @@ interface SprigrDataSearchOpts {
     page?: number;
     /** Results per page. Default 20, platform-clamped to 100. */
     hitsPerPage?: number;
+    /**
+     * LOGICAL index name — a key of the manifest's `data_indexes` map.
+     * Required for apps that declare `data_indexes` (the platform rejects a
+     * call without it, naming the declared indexes); must be OMITTED for
+     * legacy single-`data_index` apps. An undeclared name is rejected with
+     * `unknown_data_index`, never auto-created.
+     */
+    index?: string;
+    /**
+     * Explicit shard subset for a sharded logical index: `['2026']` for
+     * `shard_by: 'year'`, `['2026-05', '2026-06']` for `'month'`. Omit to
+     * search every existing shard (newest first). Narrowing here is also the
+     * escape hatch when merged pagination hits the per-shard page cap.
+     */
+    shards?: string[];
+    /**
+     * Server-side aggregations computed over ALL matching docs (not just the
+     * returned page). On a sharded logical index the platform merges shard
+     * results exactly (sum/count add, min/max take extremes, avg re-derives
+     * count-weighted).
+     */
+    aggregations?: SprigrDataAggregationSpec[];
+}
+/** One server-side aggregation. Wire fields are snake_case (platform decision 0013). */
+interface SprigrDataAggregationSpec {
+    /** Response key for this aggregation's result block. */
+    name: string;
+    /** Fold operation. `count` ignores `field`. */
+    op: 'sum' | 'avg' | 'min' | 'max' | 'count';
+    /** Numeric field to fold. Required for sum/avg/min/max. */
+    field?: string;
+    /** Bucket by this field; omit for one whole-result-set value. */
+    group_by?: string;
+}
+/** One aggregation result cell: the op value plus (for non-count ops) the numeric-value count. */
+interface SprigrDataAggregationCell {
+    sum?: number | null;
+    avg?: number | null;
+    min?: number | null;
+    max?: number | null;
+    count?: number;
+}
+interface SprigrDataAggregationResult {
+    op: 'sum' | 'avg' | 'min' | 'max' | 'count';
+    field: string | null;
+    group_by: string | null;
+    /** Present for ungrouped specs. */
+    value?: SprigrDataAggregationCell;
+    /** Present for grouped specs: bucket value -> cell. */
+    groups?: Record<string, SprigrDataAggregationCell>;
 }
 interface SprigrDataSearchResult {
     ok: boolean;
@@ -779,14 +961,34 @@ interface SprigrDataSearchResult {
     nbHits: number;
     page: number;
     facetCounts?: Record<string, Record<string, number>>;
-    /** The private index that was queried (informational). */
+    /** Present when the request carried `aggregations`. */
+    aggregations?: Record<string, SprigrDataAggregationResult>;
+    /**
+     * The logical index name for multi-index apps, else the physical index
+     * that was queried (informational).
+     */
     index: string;
+    /** Multi-index apps: the physical index/shard names this read covered. */
+    physical_indexes?: string[];
+}
+/** Options shared by data methods that can target a logical index. */
+interface SprigrDataIndexOpts {
+    /** LOGICAL index name (a `data_indexes` key). See {@link SprigrDataSearchOpts.index}. */
+    index?: string;
 }
 /**
- * The marketplace install's PRIVATE per-company datastore: a Sprigr
- * index named `<companyId>-app-<slug>`, reachable only through these
- * methods (agents have no direct index access). Injected on
- * `env.SPRIGR` by the platform wrapper for /__sprigr/* dispatch.
+ * The marketplace install's per-company datastore on Sprigr search,
+ * injected on `env.SPRIGR` by the platform wrapper for /__sprigr/*
+ * dispatch.
+ *
+ * Single-index apps (manifest `data_index`) get the fixed
+ * `<companyId>-app-<slug>` index and never pass `index`. Multi-index apps
+ * (manifest `data_indexes`, a map of logical name -> config) pass
+ * `{ index: '<logical name>' }` on EVERY call; the platform derives the
+ * physical name(s) server-side, including per-year/per-month shards for
+ * logical indexes that declare `shard_by` + an immutable ISO-date
+ * `shard_field`. Every physical index is registered with the company at
+ * creation, so agents can discover it via `sprigr_list_my_indexes`.
  *
  * Intended pattern: the app syncs lean provider objects via `import`,
  * its tool handlers call `search` to resolve a fuzzy human reference
@@ -796,30 +998,61 @@ interface SprigrDataSearchResult {
  */
 interface SprigrDataApi {
     /**
-     * Upsert objects into the private index. Each object MUST carry a
-     * unique string `objectID`. The index is auto-created on first
-     * import from the manifest's `data_index` settings; re-imports
-     * upsert by objectID. Max 1000 objects per call.
+     * Upsert objects into the store. Each object MUST carry a unique string
+     * `objectID`. Max 1000 objects per call. Indexes are auto-created on
+     * first import from the manifest settings; re-imports upsert by
+     * objectID.
+     *
+     * Sharded logical indexes route each object by its `shard_field` date;
+     * an object whose value is missing or not an ISO-8601 date string fails
+     * the WHOLE batch (`shard_field_invalid`) — fix the data, don't guess.
+     * The response's `physical_indexes` lists what was written per shard.
      */
     import(objects: Array<{
         objectID: string;
         [key: string]: unknown;
-    }>): Promise<{
+    }>, opts?: SprigrDataIndexOpts): Promise<{
         ok: boolean;
         indexed: number;
         index: string;
+        physical_indexes?: Array<{
+            index: string;
+            shard?: string;
+            indexed: number;
+        }>;
     }>;
     /**
-     * Search the private index. A never-imported index yields an empty
-     * hit list, not an error.
+     * Search the store. A never-imported index yields an empty hit list,
+     * not an error. Sharded logical indexes fan out across shards and merge
+     * (nbHits sums, facet counts sum, aggregations merge exactly; without
+     * `sortBy`, merged hits come newest shard first).
      */
     search(opts?: SprigrDataSearchOpts): Promise<SprigrDataSearchResult>;
-    /** Fetch one object by objectID. `object` is null when absent. */
-    get(objectID: string): Promise<{
+    /**
+     * Fetch one object by objectID. `object` is null when absent. On a
+     * sharded logical index the platform probes shards newest-first.
+     */
+    get(objectID: string, opts?: SprigrDataIndexOpts): Promise<{
         ok: boolean;
         object: Record<string, unknown> | null;
         index: string;
     }>;
+    /**
+     * Delete objects by objectID (mirror maintenance for source-side
+     * deletions). Idempotent: unknown ids and never-imported indexes are a
+     * no-op success. On a sharded logical index the delete fans out to
+     * every shard. `?`-optional because older platform wrapper builds
+     * predate it — feature-detect and degrade (never delete on
+     * uncertainty), per the mirror-maintenance guidance in
+     * docs/platform-reference.md.
+     */
+    delete?(objectIDs: string[], opts?: SprigrDataIndexOpts & {
+        withAcl?: boolean;
+    }): Promise<{
+        ok: boolean;
+        deleted: number;
+        index: string;
+    }>;
 }
 /**
  * Durable app file storage exposed on `env.SPRIGR.files` by the platform
@@ -992,4 +1225,4 @@ interface ExecutionContextLike {
 }
 type HandlerFn<TArgs, TResult> = (args: TArgs, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<TResult>;
 
-export { type Actor, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, type OAuthBouncerSignals, type OAuthState, type PlatformHostEnv, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type ScheduleArgs, type SprigrDataApi, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, appFileUrl, base64ToBytes, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, constantTimeEqual, createMarketplaceEmitter, decodeState, deleteAppFile, describeMissingBridge, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, getAppFile, hmacSha256Hex, installTokenPost, isStagingHost, listAppFiles, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, withSprigrEmitFallback };
+export { type Actor, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type PlatformHostEnv, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, 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 ToolResult, type ToolWrapperOptions, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, base64ToBytes, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, describeMissingBridge, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, tool, withSprigrEmitFallback };

package/dist/index.js

@@ -339,6 +339,66 @@ function ownerFromActorKey(key) {
   return null;
 }
 
+// src/tool-wrappers.ts
+var NotConnectedError = class extends Error {
+  constructor(message = "The calling actor has no connection with this app.") {
+    super(message);
+    this.name = "NotConnectedError";
+  }
+};
+function isNotConnectedError(err) {
+  if (err instanceof NotConnectedError) return true;
+  return err instanceof Error && err.name === "NotConnectedError";
+}
+var DEFAULT_NO_CALLER_HINT = "The platform did not stamp caller identity on this call. Retry from an agent context.";
+var DEFAULT_NOT_CONNECTED_HINT = "You have not connected your own account with this app yet, and this tool only ever acts as the person calling it. Use the app's connect tool to get an authorize link.";
+function shapeError(err, opts) {
+  const mapped = opts.mapError?.(err);
+  if (mapped) return { ok: false, ...mapped };
+  return { ok: false, error: err instanceof Error ? err.message : String(err) };
+}
+function tool(fn, opts = {}) {
+  return async (args, env) => {
+    try {
+      return { ok: true, result: await fn(env, args ?? {}) };
+    } catch (err) {
+      return shapeError(err, opts);
+    }
+  };
+}
+function actorTool(fn, opts = {}) {
+  return async (args, env) => {
+    const actor = parseActor(args);
+    if (!actor || !actor.platformUserId && !actor.agentId) {
+      return {
+        ok: false,
+        error: "no_caller_identity",
+        hint: opts.noCallerIdentityHint ?? DEFAULT_NO_CALLER_HINT,
+        status: 412
+      };
+    }
+    try {
+      return { ok: true, result: await fn(env, actor, args ?? {}) };
+    } catch (err) {
+      if (isNotConnectedError(err)) {
+        return {
+          ok: false,
+          error: "not_connected",
+          hint: opts.notConnectedHint ?? DEFAULT_NOT_CONNECTED_HINT,
+          status: 412
+        };
+      }
+      return shapeError(err, opts);
+    }
+  };
+}
+function createToolWrappers(opts = {}) {
+  return {
+    tool: (fn) => tool(fn, opts),
+    actorTool: (fn) => actorTool(fn, opts)
+  };
+}
+
 // src/app-files.ts
 var DEFAULT_PLATFORM_BASE = "https://webhooks.sprigr.com";
 function platformBase(env) {
@@ -428,7 +488,9 @@ function deleteAppFile(env, key) {
 export {
   DEFAULT_EMIT_TIMEOUT_MS,
   DEFAULT_MAX_FILE_BYTES,
+  NotConnectedError,
   actorKey,
+  actorTool,
   appFileUrl,
   base64ToBytes,
   buildMarketplaceWebhookUrl,
@@ -436,6 +498,7 @@ export {
   canEmit,
   constantTimeEqual,
   createMarketplaceEmitter,
+  createToolWrappers,
   decodeState,
   deleteAppFile,
   describeMissingBridge,
@@ -447,6 +510,7 @@ export {
   getAppFile,
   hmacSha256Hex,
   installTokenPost,
+  isNotConnectedError,
   isStagingHost,
   listAppFiles,
   overlaySprigr,
@@ -459,5 +523,6 @@ export {
   resolveOAuthBouncerBase,
   resolveOAuthBouncerCallbackUrl,
   resolvePlatformWebhookBase,
+  tool,
   withSprigrEmitFallback
 };

package/package.json

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