@zapier/zapier-sdk 0.84.4 → 0.86.0

package/dist/{index-ChZuXQDn.d.mts → index-Pjitof_V.d.mts}

@@ -229,31 +229,110 @@ interface SdkPage<T = unknown> {
     nextCursor?: string;
 }
 /**
- * Return type of every paginated SDK method. The same value is both:
+ * Return type of every paginated SDK method. The documented surface is:
  *
- *   - a Promise that resolves to the first page (`SdkPage<TItem>`), and
- *   - an AsyncIterable that yields each page in turn,
+ *   - `await` the result for the first page (`SdkPage<TItem>`),
+ *   - `.pages()` for an AsyncIterable over pages, and
+ *   - `.items()` for an AsyncIterable over individual items across pages.
  *
- * with an `.items()` method that returns an AsyncIterable over individual
- * items across all pages. Named so paginated plugin signatures serialize
- * as `PaginatedSdkResult<AppItem>` in `.d.ts` rather than expanding the
- * full triple-intersection at every callsite.
+ * `.pages()` and `.items()` return plain iterables (not thenables), so they
+ * survive being returned from an `async` function; the result itself is a
+ * thenable, so an `async` boundary silently collapses it to the first page.
+ * Named so paginated plugin signatures serialize as
+ * `PaginatedSdkResult<AppItem>` in `.d.ts` rather than expanding the full
+ * intersection at every callsite.
  *
  * The faces share one underlying cursor, so a result is consumed once:
  *
  *   - `await` / `.then()` read the buffered first page without starting the
  *     stream, so awaiting is a repeatable peek and you can still iterate the
  *     result afterward.
- *   - The page-iterable and `.items()` are two views over one page stream, so
- *     consuming either drains the other: the second view yields nothing (it
- *     does not replay page 1). To read a result more than once, call the
- *     method again for a fresh result.
+ *   - `.pages()`, `.items()`, and the deprecated bare iteration are views
+ *     over one page stream, so consuming any view drains the others: the
+ *     second view yields nothing (it does not replay page 1). To read a
+ *     result more than once, call the method again for a fresh result.
  */
-interface PaginatedSdkResult<TItem> extends Promise<SdkPage<TItem>>, AsyncIterable<SdkPage<TItem>> {
+interface PaginatedSdkResult<TItem> extends Promise<SdkPage<TItem>> {
+    /**
+     * @deprecated Iterate `.pages()` instead. Bare iteration works but is easy
+     * to break: because the result is also a thenable, an `async` boundary
+     * collapses it to its first page and the iterable is silently lost.
+     *
+     * Deliberately no runtime deprecation warning: this face is not scheduled
+     * for deletion (removing it is a breaking change deferred to a separate
+     * decision), and structural consumers such as the CLI's page streaming
+     * detect pagination via `Symbol.asyncIterator`, so a warning would fire on
+     * the SDK's own machinery.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<SdkPage<TItem>>;
+    pages(): AsyncIterable<SdkPage<TItem>>;
     items(): AsyncIterable<TItem>;
 }
 type PaginatedSdkFunction<TOptions, TItem> = (options: TOptions) => PaginatedSdkResult<TItem>;
 
+/**
+ * Per-call context threaded explicitly through the method boundary in place of
+ * ambient AsyncLocalStorage. It carries call identity, nesting depth, and a
+ * per-invocation annotation bag. Because it travels as data, correlation and
+ * nested-call dedup work without `async_hooks` — including in browsers, where
+ * the old ALS store was inert and nested calls all looked top-level.
+ *
+ * Framework-neutral: heads surface `callId` under their own name (e.g. a
+ * correlation id) and own their annotation field names.
+ */
+/**
+ * A private brand (a fresh `Symbol()`, never `Symbol.for`) makes a CallContext
+ * unforgeable: no outside code can name the symbol to synthesize an id-bearing
+ * context, and the brand never collides across bundled copies. This is the same
+ * unforgeability the `INTERNAL_CALL` sentinel relies on.
+ */
+declare const CALL_CONTEXT_BRAND: unique symbol;
+interface CallContext {
+    /** Minted once at the root call; copied verbatim to every nested (child) call. */
+    callId: string | null;
+    /** 0 at the outermost call; `parent.depth + 1` for a delegated call. */
+    depth: number;
+    /**
+     * Per-invocation scratch space. Never forwarded to callees — a child call
+     * gets a fresh bag — so annotations describe one method's own invocation.
+     */
+    annotations: Record<string, unknown>;
+    readonly [CALL_CONTEXT_BRAND]: true;
+}
+
+/**
+ * Method-call lifecycle hooks. Plugins contribute `onMethodStart` and/or
+ * `onMethodEnd` on their context; `buildHooks` composes contributions across
+ * plugins so multiple observers can coexist. Composition is right-additive
+ * (newer plugins fire after earlier ones); only opt-in methods built through
+ * `createPluginMethod` / `createPaginatedPluginMethod` trigger the hooks.
+ */
+interface OnMethodStartContext {
+    methodName: string;
+    args: unknown[];
+    isPaginated: boolean;
+    /**
+     * Depth of this method invocation in the SDK call tree. 0 = outermost
+     * (user-initiated) call; 1+ = called from inside another SDK method.
+     * Observers can use this to ignore nested calls if they only want
+     * top-level events.
+     */
+    depth: number;
+}
+type OnMethodStart = (ctx: OnMethodStartContext) => void;
+interface OnMethodEndContext {
+    methodName: string;
+    args: unknown[];
+    isPaginated: boolean;
+    depth: number;
+    durationMs: number;
+    error?: Error;
+}
+type OnMethodEnd = (ctx: OnMethodEndContext) => void;
+interface MethodHooks {
+    onMethodStart?: OnMethodStart;
+    onMethodEnd?: OnMethodEnd;
+}
 interface FormattedItem {
     title: string;
     /**
@@ -344,8 +423,6 @@ type ListPromptConfig = PromptConfig & {
  *  - `filter`  — no resolver uses it; transform values in `listItems` instead.
  *  - `validate`— validation is the resolver's top-level `validate`, which
  *    never routes through rendering (and gets `imports`).
- * (The legacy `SchemaParameterResolver` still honors `default`/`filter`/
- * `validate`, so the full `PromptConfig` stays for that path.)
  */
 type ResolverPromptConfig = Omit<PromptConfig, "name" | "default" | "filter" | "validate">;
 interface Resolver$1 {
@@ -515,40 +592,6 @@ interface PositionalMetadata {
 }
 declare function isPositional(schema: z.ZodType): boolean;
 
-/**
- * Method-call lifecycle hooks. Plugins contribute `onMethodStart` and/or
- * `onMethodEnd` on their context; `buildHooks` composes contributions across
- * plugins so multiple observers can coexist. Composition is right-additive
- * (newer plugins fire after earlier ones); only opt-in methods built through
- * `createPluginMethod` / `createPaginatedPluginMethod` trigger the hooks.
- */
-interface OnMethodStartContext {
-    methodName: string;
-    args: unknown[];
-    isPaginated: boolean;
-    /**
-     * Depth of this method invocation in the SDK call tree. 0 = outermost
-     * (user-initiated) call; 1+ = called from inside another SDK method.
-     * Observers can use this to ignore nested calls if they only want
-     * top-level events.
-     */
-    depth: number;
-}
-type OnMethodStart = (ctx: OnMethodStartContext) => void;
-interface OnMethodEndContext {
-    methodName: string;
-    args: unknown[];
-    isPaginated: boolean;
-    depth: number;
-    durationMs: number;
-    error?: Error;
-}
-type OnMethodEnd = (ctx: OnMethodEndContext) => void;
-interface MethodHooks {
-    onMethodStart?: OnMethodStart;
-    onMethodEnd?: OnMethodEnd;
-}
-
 /**
  * Descriptive metadata a leaf carries for the registry / CLI / MCP / docs:
  * description, categories, type, formatter, resolvers, etc.
@@ -571,10 +614,6 @@ interface LeafMetaFields {
     itemType?: string;
     returnType?: string;
     outputSchema?: z.ZodSchema;
-    inputParameters?: Array<{
-        name: string;
-        schema: z.ZodSchema;
-    }>;
     packages?: string[];
     experimental?: boolean;
     confirm?: "create-secret" | "delete";
@@ -740,12 +779,11 @@ interface DynamicResolver extends ResolverBase {
         input: Record<string, unknown>;
     }) => PromiseLike<unknown>;
     /** Produce the candidate list. Behaves like an SDK list method: returns a
-     * paginated result (await for the first page + `nextCursor`, or iterate pages),
-     * never a bare array. `cursor` is the stateless re-entry hook for "load more":
-     * an in-process host iterates the result; a distributed host awaits one page,
-     * carries `nextCursor`, and calls again with `cursor`. Required: a dynamic
-     * resolver IS a candidate-lister; a free-text field (with or without
-     * auto-resolution someday) is the `static` kind's job. */
+     * paginated result (the engine awaits the first page + `nextCursor`), never a
+     * bare array. `cursor` is the stateless re-entry hook for "load more": the
+     * engine awaits one page, carries `nextCursor`, and calls again with `cursor`.
+     * Required: a dynamic resolver IS a candidate-lister; a free-text field (with
+     * or without auto-resolution someday) is the `static` kind's job. */
     listItems: (bag: {
         imports: Record<string, unknown>;
         input: Record<string, unknown>;
@@ -829,6 +867,27 @@ interface ObjectResolver extends ResolverBase {
         input: Record<string, unknown>;
     }) => PromiseLike<Record<string, Field$1>>;
     definitions?: Record<string, Resolver>;
+    /** Open-ended entries whose keys aren't known up front (a `z.record`): the
+     * walk collects entries in an add/done loop, asking each entry's key (via
+     * `keys`, default a free-text string) then its value (via `values`), and
+     * assembling them onto the object alongside any fixed `properties`. The
+     * JSON-Schema `additionalProperties` analog. */
+    additionalKeys?: AdditionalKeys;
+}
+/** The open-keyed-entry spec for an {@link ObjectResolver.additionalKeys}. */
+interface AdditionalKeys {
+    /** Resolver for each entry's key; defaults to a free-text string prompt. A
+     * `{ ref }` resolves against the object's `definitions`. */
+    keys?: Resolver | ResolverRef;
+    /** Resolver for each entry's value. A `{ ref }` resolves against the
+     * object's `definitions`. */
+    values: Resolver | ResolverRef;
+    minEntries?: number;
+    maxEntries?: number;
+    /** Coarse value types so a free-text key/value answer coerces (usually
+     * `"string"` for the key), the way `Field.valueType` does. */
+    keyValueType?: string;
+    valueValueType?: string;
 }
 /** A homogeneous list: each element resolves through `items`. */
 interface ArrayResolver extends ResolverBase {
@@ -874,9 +933,9 @@ interface Formatter extends MethodAttachment {
     }) => FormattedItem;
 }
 /** What a dynamic resolver's `listItems` yields: an SDK list-method result
- * (`await` for the first page + `nextCursor`, or iterate pages in-process), or a
- * plain page / promise of one. No bare array and no scalar: it behaves like any
- * other list method, and exact-match short-circuits live on `tryResolveFromSearch`. */
+ * (the engine awaits the first page + `nextCursor`), or a plain page / promise
+ * of one. No bare array and no scalar: it behaves like any other list method,
+ * and exact-match short-circuits live on `tryResolveFromSearch`. */
 type ListItemsResult<TItem> = PaginatedSdkResult<TItem> | SdkPage<TItem> | Promise<SdkPage<TItem>>;
 /** A bound object resolver's literal property: its resolver is already bound
  * (or a `{ ref }` the CLI resolves against `definitions` at runtime). */
@@ -947,7 +1006,8 @@ interface BoundDynamicResolver extends BoundResolverBase {
     } | null>;
 }
 /** Keyed members: static `properties` (bound) or a `getProperties`-built
- * (unbound) field map; `definitions` holds ref targets. */
+ * (unbound) field map; `definitions` holds ref targets. `additionalKeys`
+ * carries open-ended entries (a `z.record`). */
 interface BoundObjectResolver extends BoundResolverBase {
     type: "object";
     properties?: Record<string, BoundField>;
@@ -955,6 +1015,17 @@ interface BoundObjectResolver extends BoundResolverBase {
     getProperties?: (bag: {
         input: Record<string, unknown>;
     }) => PromiseLike<Record<string, Field$1>>;
+    additionalKeys?: BoundAdditionalKeys;
+}
+/** The bound form of {@link AdditionalKeys}: `keys`/`values` are bound (or a
+ * `{ ref }` into the object's `definitions`). */
+interface BoundAdditionalKeys {
+    keys?: BoundResolver | ResolverRef;
+    values: BoundResolver | ResolverRef;
+    minEntries?: number;
+    maxEntries?: number;
+    keyValueType?: string;
+    valueValueType?: string;
 }
 /** A homogeneous list resolved through `items` (bound, or a ref into
  * `definitions`). */
@@ -1345,9 +1416,18 @@ interface MethodEntry {
      * `resolvePlugin` bind this; the surface and registry bind `value`. Absent
      * on legacy graph entries (they bind `value`). */
     internalValue?: (input: any) => any;
+    /** Produce the import-facing twin for a given call context: with a context,
+     * the twin mints a fresh child per invocation (callee inherits `callId`, sits
+     * one level deeper); without one it is the parent-less `internalValue`.
+     * `buildImports` binds this. Absent on legacy graph entries. */
+    bindInternal?: (ctx?: CallContext) => (...args: any[]) => any;
     chain: MiddlewareWrap[];
     /** Carried from the descriptor for the registry / CLI / MCP / docs. */
     inputSchema?: z.ZodType;
+    /** When true, the method owns its input validation and the boundary passes it
+     * through unparsed; carried so the controller skips its final `safeParse` too
+     * (it still uses `inputSchema` to plan/prompt parameters). */
+    skipInputValidation?: boolean;
     meta?: LeafMeta;
     /** Resolved output mode; the registry derives presentation from it. */
     output?: NormalizedOutput;
@@ -1592,7 +1672,7 @@ interface CategoryDefinition {
     /** Plural form of `title`. Auto-derived from the resolved title if omitted. */
     titlePlural?: string;
 }
-interface FunctionRegistryEntry<TSdk = any> {
+interface FunctionRegistryEntry {
     name: string;
     /**
      * Human-readable description of the function. Surfaced wherever the
@@ -1605,29 +1685,30 @@ interface FunctionRegistryEntry<TSdk = any> {
     itemType?: string;
     returnType?: string;
     inputSchema?: z.ZodSchema;
-    inputParameters?: Array<{
-        name: string;
-        schema: z.ZodSchema;
-    }>;
+    /**
+     * When true, the method owns its input validation and its boundary passes the
+     * input through unparsed. The resolution controller reads this to skip its
+     * final `safeParse` (it still uses `inputSchema` to plan/prompt parameters),
+     * so a method routed through the controller isn't re-validated against a
+     * schema it deliberately opts out of. Lifted off the materialized entry.
+     */
+    skipInputValidation?: boolean;
     outputSchema?: z.ZodSchema;
     /**
      * Ordered input keys the public surface projects onto positional arguments
      * (the method's `positional` declaration). Absent when the method takes only
      * the canonical single bag. Lifted off the materialized method entry by the
-     * surface builder, like `boundResolvers` — a runtime projection, not
+     * surface builder, like `resolvers` — a runtime projection, not
      * descriptive meta.
      */
     positional?: readonly string[];
     categories: string[];
-    resolvers?: Record<string, ResolverMetadata<TSdk, any, any>>;
     /**
-     * Per-parameter bound resolvers from the new model (imports already captured,
-     * called with `input` only, no sdk). Parallel to the legacy `resolvers` field
-     * and `formatter`: the surface builder lifts these off the materialized method
-     * entry. Additive bridge — populated for migrated `defineMethod` plugins; the
-     * legacy `resolvers` field above stays the source for unmigrated ones.
+     * Per-parameter bound resolvers (imports already captured, called with
+     * `input` only, no sdk). Lifted off the materialized method entry by the
+     * surface builder.
      */
-    boundResolvers?: Record<string, BoundResolver>;
+    resolvers?: Record<string, BoundResolver>;
     packages?: string[];
     /**
      * True if the plugin is registered only in the experimental SDK
@@ -1661,8 +1742,8 @@ interface FunctionDeprecation {
     /** User-facing deprecation message for why/how to migrate */
     message: string;
 }
-interface RegistryResult<TSdk = any> {
-    functions: FunctionRegistryEntry<TSdk>[];
+interface RegistryResult {
+    functions: FunctionRegistryEntry[];
     categories: {
         key: string;
         title: string;
@@ -1767,7 +1848,7 @@ type Sdk<T = {
 }> = T & {
     getRegistry(options?: {
         package?: string;
-    }): RegistryResult<T>;
+    }): RegistryResult;
 };
 
 /**
@@ -2355,6 +2436,8 @@ declare function defineResolver<const TImports extends ImportsInput = readonly [
         input: TInput;
     }) => PromiseLike<Record<string, Field$1>>;
     definitions?: Record<string, Resolver>;
+    /** Open-ended entries whose keys aren't known up front (a `z.record`). */
+    additionalKeys?: AdditionalKeys;
 }): ObjectResolver;
 declare function defineResolver(config: {
     type: "array";
@@ -2729,7 +2812,7 @@ interface CoreOptions {
  */
 declare const getRegistryPlugin: MethodPlugin<"getRegistry", {
     package?: string | undefined;
-} | undefined, RegistryResult<any>, readonly []> & LeafSummary<"kitcore", "getRegistry", readonly [PropertyPlugin<"context", SdkContext>]>;
+} | undefined, RegistryResult, readonly []> & LeafSummary<"kitcore", "getRegistry", readonly [PropertyPlugin<"context", SdkContext>]>;
 
 /**
  * The external escape-hatch key for an SDK's context. A Symbol,
@@ -2890,13 +2973,13 @@ type ControllerQuestion = {
     path: ControllerPath;
     message: string;
     description?: string;
-    /** Which container kind this decision gates. `array` is the add-another
-     * loop; `object` is the entry gate on an optional object, fired BEFORE
-     * its fields are fetched (`add` descends into the fields, `done` skips
-     * the container). A host that renders `message` + `actions` generically
-     * needs nothing else; this is additive metadata for hosts that render
-     * containers specially. */
-    container: "array" | "object";
+    /** Which container type this decision is about. `array`/`record` are the
+     * add-another loops; `object` covers both the optional-object gate (fired
+     * BEFORE its fields are fetched: `add` descends, `done` skips it) and the
+     * optional-fields gate. A host that renders `message` + `actions`
+     * generically needs nothing else; this is additive metadata for hosts
+     * that render containers specially. */
+    container: "array" | "object" | "record";
     /** Object optionals gate only: the fields the `add` action would walk
      * (key + display label + coarse value type), so a smart host can render
      * them (or a form section) instead of a blind yes/no. Dumb hosts keep
@@ -3005,11 +3088,16 @@ interface ControllerState {
     /** The path of the parameter (or nested field) currently being asked. */
     current?: ControllerPath;
     /** Which container decision the outstanding `collection` question is, when
-     * `current` points at one: the array add/done loop, an optional object's
-     * entry gate, or an object's optionals gate. Recorded explicitly so `step`'s
-     * add/done handling never infers the decision from value presence or
-     * resolver shape. Absent when `current` is a plain leaf question. */
-    gate?: "array" | "entry" | "optionals";
+     * `current` points at one, named `<container>_<subject>`: `array_items` and
+     * `record_entries` are the add/done loops; `object_optional` is whether to
+     * provide an optional object at all (fired before its fields are fetched);
+     * `object_optional_properties` is whether to fill that object's optional
+     * fields. `record_key` marks the one bespoke record step (collecting an
+     * entry's key); the value that follows is an ordinary leaf question with no
+     * gate. Recorded explicitly so `step`'s handling never infers the decision
+     * from value presence or resolver shape. Absent when `current` is a plain
+     * leaf question. */
+    gate?: "array_items" | "record_entries" | "record_key" | "object_optional" | "object_optional_properties";
     /** Where pagination stands for the current dynamic leaf: coordinates only
      * (cursor trail, generation), never items or live iterators — the page's
      * items ride the ask's question. */
@@ -3228,7 +3316,7 @@ type FunctionSdk = {
  *                      and `context.core`
  * @param options.schema - optional Zod schema for input validation
  */
-declare function createFunction<TOptions, TResult, TSchemaOptions extends TOptions = TOptions>(coreFn: (options: TOptions) => Promise<TResult>, options: {
+declare function createFunction<TOptions, TResult, TSchemaOptions extends TOptions = TOptions>(coreFn: (options: TOptions, context?: CallContext) => Promise<TResult>, options: {
     sdk: FunctionSdk;
     schema?: z.ZodSchema<TSchemaOptions>;
     name?: string;
@@ -3254,7 +3342,7 @@ type ItemType<TResult> = TResult extends {
 declare function createPaginatedFunction<TUserOptions, TResponse, TItem = ItemType<TResponse>>(coreFn: (options: TUserOptions & {
     cursor?: string;
     pageSize?: number;
-}) => Promise<TResponse>, options: {
+}, context?: CallContext) => Promise<TResponse>, options: {
     sdk: FunctionSdk;
     schema?: z.ZodSchema<TUserOptions>;
     name?: string;
@@ -7347,7 +7435,7 @@ interface ZapierSdkOptions extends BaseSdkOptions {
 declare function createZapierSdkWithoutRegistry(options?: ZapierSdkOptions): {
     getRegistry: (input?: {
         package?: string | undefined;
-    } | undefined) => RegistryResult<any>;
+    } | undefined) => RegistryResult;
     getProfile: (input?: Record<string, never> | undefined) => Promise<{
         data: {
             id: string;
@@ -8792,7 +8880,7 @@ declare function createZapierSdkWithoutRegistry(options?: ZapierSdkOptions): {
 declare const zapierSdkPlugin: AggregatePlugin<"sdk", {
     getRegistry: MethodPlugin<"getRegistry", {
         package?: string | undefined;
-    } | undefined, RegistryResult<any>, readonly []> & LeafSummary<"kitcore", "getRegistry", readonly [PropertyPlugin<"context", SdkContext>]>;
+    } | undefined, RegistryResult, readonly []> & LeafSummary<"kitcore", "getRegistry", readonly [PropertyPlugin<"context", SdkContext>]>;
 } & {
     getProfile: MethodPlugin<"getProfile", Record<string, never> | undefined, Promise<{
         data: {
@@ -11555,7 +11643,7 @@ declare const zapierSdkPlugin: AggregatePlugin<"sdk", {
 declare function createZapierSdk(options?: ZapierSdkOptions): {
     getRegistry: (input?: {
         package?: string | undefined;
-    } | undefined) => RegistryResult<any>;
+    } | undefined) => RegistryResult;
     getProfile: (input?: Record<string, never> | undefined) => Promise<{
         data: {
             id: string;