@sprigr/apps-app-sdk 0.15.2 → 0.16.0

package/README.md

@@ -44,6 +44,28 @@ export default { list_things: actorTool(async (env, actor, args) => { /* ... */
 
 **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.
 
+## Retiring a person or agent: `on_actor_retired`
+
+A per-actor app must forget a person when the platform does. When a member is removed, an agent is deleted, a companion's bound user id is corrected, or an operator retires an orphaned key, the platform POSTs `/__sprigr/tool/on_actor_retired` to every install that declares a tool of that name (sprigr-team decision 0154). Run the same revoke-and-purge your own disconnect tool runs, for that key only.
+
+```ts
+import { actorRetiredHook } from '@sprigr/apps-app-sdk';
+
+export default {
+  on_actor_retired: actorRetiredHook<MyEnv>(async (env, retired) => {
+    // retired.actor is shaped like a stamped actor: actorKey(retired.actor) === retired.actorKey
+    await revokeAndPurge(env, retired.actor, { cutoff: retired.requestedAt, ownerRef: retired.storageOwnerRef });
+    return { done: true };
+  }),
+};
+```
+
+- Declare it in `tools[]` with `"internal": true`. The platform never lets an agent or the app bridge call it.
+- `actorRetiredHook` refuses a call that carries `args.actor` (the platform's dispatch never does) and a malformed body, by throwing. It never turns a throw into `{ ok: false }`: the platform reads `done`, and a swallowed error would read as finished. A throw is retried.
+- Return `{ done: true }` when finished or durably queued by the app; `{ done: false, remaining }` to be called again (1 min up to 12 h, 8 deliveries). Be idempotent.
+- `successorKey` is audit only: never move the grant or the data to it. Delete only what existed by `requestedAt`.
+- `storageOwnerRef` is the `owner_ref` a no-actor maintenance `env.SPRIGR.files.list` reports for this person's per-user stored files; pass it to a no-actor `files.delete(key, { owner_ref })`.
+
 ## Webhook callback URLs
 
 - `resolvePlatformWebhookBase(env)` / `buildMarketplaceWebhookUrl(env, installId, topicPath)` — env-correct platform host, so a staging install never registers prod-pointing subscriptions.

package/dist/index.d.ts

@@ -1185,6 +1185,113 @@ declare function createToolWrappers<Env>(opts?: ToolWrapperOptions): {
     actorTool: <A, R>(fn: (env: Env, actor: Actor, args: A) => Promise<R>) => (args: A, env: Env) => Promise<ToolResult<R>>;
 };
 
+/**
+ * The `on_actor_retired` lifecycle hook (sprigr-team decision 0154,
+ * sprigr/sprigr-team#10109).
+ *
+ * A per-actor app keys a person's connection, tokens and data on the key
+ * `actorKey()` derives: `u:<platformUserId>`, else `a:<agentId>`. When that
+ * identity goes away (a member is removed, an agent is deleted, a companion's
+ * bound user id is corrected, or an operator retires an orphan), the platform
+ * POSTs `/__sprigr/tool/on_actor_retired` to every install that declares a
+ * tool of that name. The app should run its own self-disconnect
+ * revoke-and-purge for that key and nothing else.
+ *
+ *   // src/handlers/index.ts
+ *   import { actorRetiredHook } from '@sprigr/apps-app-sdk';
+ *   export default {
+ *     on_actor_retired: actorRetiredHook<MyEnv>(async (env, retired) => {
+ *       await revokeAndPurge(env, retired.actor, { cutoff: retired.requestedAt, ownerRef: retired.storageOwnerRef });
+ *       return { done: true };
+ *     }),
+ *   };
+ *
+ * Manifest: declare the tool with `"internal": true`. The platform keeps it
+ * off every agent tool list and refuses it on the app-bridge invoke route
+ * either way, because its body names whose grant to revoke.
+ *
+ * Contract:
+ *   - The dispatch carries NO actor. `actorRetiredHook` throws when `args.actor`
+ *     is present (a call that did not come from this hook), and when the body
+ *     is malformed. A throw reaches the platform as a 500, which it retries
+ *     and finally logs, so a contract mismatch is loud rather than a silent
+ *     "done".
+ *   - Return `{ done: true }` when finished, or when the rest is durably
+ *     queued by the app itself. Return `{ done: false, remaining }` to be
+ *     called again later (1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h; 8
+ *     deliveries in all). A thrown error is retried the same way.
+ *   - Idempotent: a second delivery for a key already purged must return
+ *     `{ done: true }`.
+ *   - `successorKey` is audit only. Never move the grant or the data to it.
+ *   - Delete only what existed by `requestedAt`.
+ *   - `storageOwnerRef` is the `owner_ref` a no-actor maintenance
+ *     `env.SPRIGR.files.list` reports for this person's per-user stored files;
+ *     pass it to a no-actor `env.SPRIGR.files.delete(key, { owner_ref })`.
+ *     Only the platform can derive it.
+ */
+
+/** The manifest tool name the platform dispatches. */
+declare const ACTOR_RETIRED_HOOK_TOOL = "on_actor_retired";
+/** Why the key is being retired. */
+type ActorRetireReason = 'member_removed' | 'agent_deleted' | 'user_id_superseded' | 'admin_removed';
+declare const ACTOR_RETIRE_REASONS: readonly ActorRetireReason[];
+/** The wire body, exactly as the platform POSTs it (snake_case). */
+interface ActorRetiredHookBody {
+    trigger: 'actor_retired';
+    install_id: string;
+    company_id: string;
+    /** `u:<platform_user_id>` or `a:<agent_id>`. */
+    actor_key: string;
+    platform_user_id?: string;
+    agent_id?: string;
+    reason: ActorRetireReason;
+    /** Audit only. */
+    successor_key?: string;
+    /** 32 hex chars: the per-user storage owner (`owner_ref`). */
+    storage_owner_ref: string;
+    requested_by?: string;
+    /** ISO time; purge only what existed by then. */
+    requested_at: string;
+    /** 1 on the first delivery. */
+    attempt: number;
+}
+/** The parsed body a handler receives. */
+interface ActorRetired {
+    installId: string;
+    companyId: string;
+    /** The app-side key, equal to `actorKey(actor)`. */
+    actorKey: string;
+    /** The retired identity, shaped like a stamped actor so existing per-actor
+     *  helpers (token stores, walk keys) can be called with it. */
+    actor: Actor;
+    reason: ActorRetireReason;
+    successorKey?: string;
+    storageOwnerRef: string;
+    requestedBy?: string;
+    /** Epoch ms of `requested_at`. */
+    requestedAt: number;
+    attempt: number;
+}
+/** What the handler returns. */
+interface ActorRetiredResult {
+    done: boolean;
+    /** Anything that says what is left, for the platform's log. */
+    remaining?: unknown;
+    [extra: string]: unknown;
+}
+/**
+ * Parse and check the hook body. Throws an Error naming the first problem;
+ * never returns a partial value.
+ */
+declare function parseActorRetiredArgs(args: unknown): ActorRetired;
+/**
+ * Wrap an `on_actor_retired` handler in the wrapper's `(args, env)` calling
+ * convention. Unlike `tool()` it does NOT turn a throw into `{ ok: false }`:
+ * the platform reads the returned `done`, and a swallowed error would read as
+ * finished. A throw becomes a 500 the platform retries.
+ */
+declare function actorRetiredHook<Env>(fn: (env: Env, retired: ActorRetired) => Promise<ActorRetiredResult>): (args: unknown, env: Env) => Promise<ActorRetiredResult>;
+
 /**
  * App-scoped R2 file storage (platform feature, 2026-06).
  *
@@ -2920,4 +3027,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 AppToolEffectsDeclaration, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type ConnectCompleteRequest, type ConnectCompleteResult, type D1Like, type D1PreparedStatementLike, DATA_PARTIAL_UPDATE_PATH, 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, INBOX_SEND_CONTRACT_V1, type InboxAddress, type InboxAppendRequest, type InboxAppendResult, type InboxChannelDeclaration, type InboxFoldersRequest, type InboxFoldersResult, type InboxOwner, type InboxSendConnection, type InboxSendHandlerImpl, InboxSendRefusal, type InboxSendSupports, type InboxSendV1Args, type InboxSendV1Result, 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 PartialUpdateDataOptions, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type ResolveViewerOptions, type RestoreResult, type RestoreSpec, SPRIGR_DATA_MAX_OBJECTS_PER_CALL, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataImportOpts, type SprigrDataIndexOpts, type SprigrDataPartialUpdateBody, type SprigrDataPartialUpdateOpts, type SprigrDataPartialUpdateResult, type SprigrDataPatch, type SprigrDataSearchOpts, type SprigrDataSearchResult, SprigrDataValidationError, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type SprigrFilesListItem, type SprigrFilesListResult, type SprigrInboxApi, type SprigrLogEntry, type SprigrLogFn, type SprigrLogLevel, type SprigrLogResult, SprigrLogValidationError, type SyncedAttachment, type SyncedMessage, 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, buildPartialUpdateBody, bytesToBase64, canEmit, canLog, canPartialUpdate, checkConfirmationPolicy, commonDestructiveVerbs, connectComplete, connectDisconnect, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, defineInboxSendHandler, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, partialUpdateData, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrInboxFallback, withSprigrLogFallback };
+export { ACTOR_RETIRED_HOOK_TOOL, ACTOR_RETIRE_REASONS, APPROVAL_GRANTED_KEY, type Actor, type ActorRetireReason, type ActorRetired, type ActorRetiredHookBody, type ActorRetiredResult, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppToolEffectsDeclaration, type AppUndoEnvelope, type ApplyPoliciesOptions, type ApprovalGateOptions, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type ConnectCompleteRequest, type ConnectCompleteResult, type D1Like, type D1PreparedStatementLike, DATA_PARTIAL_UPDATE_PATH, 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, INBOX_SEND_CONTRACT_V1, type InboxAddress, type InboxAppendRequest, type InboxAppendResult, type InboxChannelDeclaration, type InboxFoldersRequest, type InboxFoldersResult, type InboxOwner, type InboxSendConnection, type InboxSendHandlerImpl, InboxSendRefusal, type InboxSendSupports, type InboxSendV1Args, type InboxSendV1Result, 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 PartialUpdateDataOptions, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type ResolveViewerOptions, type RestoreResult, type RestoreSpec, SPRIGR_DATA_MAX_OBJECTS_PER_CALL, SPRIGR_LOG_LEVELS, SPRIGR_LOG_LIMITS, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataImportOpts, type SprigrDataIndexOpts, type SprigrDataPartialUpdateBody, type SprigrDataPartialUpdateOpts, type SprigrDataPartialUpdateResult, type SprigrDataPatch, type SprigrDataSearchOpts, type SprigrDataSearchResult, SprigrDataValidationError, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type SprigrFilesListItem, type SprigrFilesListResult, type SprigrInboxApi, type SprigrLogEntry, type SprigrLogFn, type SprigrLogLevel, type SprigrLogResult, SprigrLogValidationError, type SyncedAttachment, type SyncedMessage, 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, actorRetiredHook, actorTool, appFileUrl, applyConfirmationPolicies, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, buildPartialUpdateBody, bytesToBase64, canEmit, canLog, canPartialUpdate, checkConfirmationPolicy, commonDestructiveVerbs, connectComplete, connectDisconnect, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, defineInboxSendHandler, deleteAppFile, deriveConfirmationPolicy, describeMissingBridge, dispatcherApproval, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, logToPlatform, manifestIsFresh, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, parseActorRetiredArgs, partialUpdateData, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, resolveViewerContext, resolveViewerUserId, runUndoApply, safeCapture, seq, serializeManifest, set, tool, undoEnvelope, validateLogEntries, validateLogEntry, verifyViewerToken, withSprigrEmitFallback, withSprigrInboxFallback, withSprigrLogFallback };

package/dist/index.js

@@ -840,6 +840,74 @@ function createToolWrappers(opts = {}) {
   };
 }
 
+// src/lifecycle.ts
+var ACTOR_RETIRED_HOOK_TOOL = "on_actor_retired";
+var ACTOR_RETIRE_REASONS = [
+  "member_removed",
+  "agent_deleted",
+  "user_id_superseded",
+  "admin_removed"
+];
+var OWNER_REF_RE = /^[0-9a-f]{32}$/;
+var KEY_RE = /^([ua]):([A-Za-z0-9_\-.:@]{1,200})$/;
+function parseActorRetiredArgs(args) {
+  if (!args || typeof args !== "object") throw new Error("on_actor_retired: body is not an object");
+  const b = args;
+  if (b.actor !== void 0 && b.actor !== null) {
+    throw new Error("on_actor_retired: refused, the call carries an actor; only the platform hook may call this");
+  }
+  if (b.trigger !== "actor_retired") throw new Error(`on_actor_retired: trigger must be actor_retired, got ${String(b.trigger)}`);
+  const str = (k) => {
+    const v = b[k];
+    if (typeof v !== "string" || v === "") throw new Error(`on_actor_retired: ${k} is required`);
+    return v;
+  };
+  const installId = str("install_id");
+  const companyId = str("company_id");
+  const key = str("actor_key");
+  const m = KEY_RE.exec(key);
+  if (!m) throw new Error(`on_actor_retired: actor_key must be u:<id> or a:<id>, got ${key.slice(0, 80)}`);
+  const actor = m[1] === "u" ? { platformUserId: m[2] } : { agentId: m[2] };
+  if (m[1] === "u" && b.platform_user_id !== void 0 && b.platform_user_id !== m[2]) {
+    throw new Error("on_actor_retired: platform_user_id does not match actor_key");
+  }
+  if (m[1] === "a" && b.agent_id !== void 0 && b.agent_id !== m[2]) {
+    throw new Error("on_actor_retired: agent_id does not match actor_key");
+  }
+  if (actorKey(actor) !== key) throw new Error("on_actor_retired: actor_key does not round-trip");
+  const reason = b.reason;
+  if (typeof reason !== "string" || !ACTOR_RETIRE_REASONS.includes(reason)) {
+    throw new Error(`on_actor_retired: unknown reason ${String(reason)}`);
+  }
+  const storageOwnerRef = str("storage_owner_ref");
+  if (!OWNER_REF_RE.test(storageOwnerRef)) throw new Error("on_actor_retired: storage_owner_ref must be 32 lowercase hex characters");
+  const requestedAt = Date.parse(str("requested_at"));
+  if (!Number.isFinite(requestedAt)) throw new Error("on_actor_retired: requested_at is not a date");
+  const attempt = typeof b.attempt === "number" && b.attempt >= 1 ? b.attempt : 1;
+  return {
+    installId,
+    companyId,
+    actorKey: key,
+    actor,
+    reason,
+    ...typeof b.successor_key === "string" && b.successor_key ? { successorKey: b.successor_key } : {},
+    storageOwnerRef,
+    ...typeof b.requested_by === "string" && b.requested_by ? { requestedBy: b.requested_by } : {},
+    requestedAt,
+    attempt
+  };
+}
+function actorRetiredHook(fn) {
+  return async (args, env) => {
+    const retired = parseActorRetiredArgs(args);
+    const result = await fn(env, retired);
+    if (!result || typeof result.done !== "boolean") {
+      throw new Error("on_actor_retired: the handler must return { done: boolean }");
+    }
+    return result;
+  };
+}
+
 // src/app-files.ts
 var DEFAULT_PLATFORM_BASE = "https://webhooks.sprigr.com";
 function platformBase(env) {
@@ -1617,6 +1685,8 @@ async function connectDisconnect(env, req) {
   return await installTokenPost(bridge, "/internal/wfp/connect/disconnect", req, { label: "connect disconnect" });
 }
 export {
+  ACTOR_RETIRED_HOOK_TOOL,
+  ACTOR_RETIRE_REASONS,
   APPROVAL_GRANTED_KEY,
   DATA_PARTIAL_UPDATE_PATH,
   DEFAULT_EMIT_TIMEOUT_MS,
@@ -1640,6 +1710,7 @@ export {
   VIEWER_ROLE_HEADER,
   VIEWER_USER_ID_HEADER,
   actorKey,
+  actorRetiredHook,
   actorTool,
   appFileUrl,
   applyConfirmationPolicies,
@@ -1684,6 +1755,7 @@ export {
   overlaySprigr,
   ownerFromActorKey,
   parseActor,
+  parseActorRetiredArgs,
   partialUpdateData,
   putAppFile,
   putAppFileStream,

package/package.json

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