@zapier/kitcore 0.6.0 → 0.8.0

package/dist/index.d.mts

@@ -20,27 +20,43 @@ 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>;
@@ -134,15 +150,17 @@ type ListPromptConfig = PromptConfig & {
 };
 /**
  * The prompt config the NEW-model resolvers (`defineResolver`) return. It omits
- * three fields the resolution controller does not honor, so authors can't
+ * four fields the resolution controller does not honor, so authors can't
  * supply a silent no-op:
- *  - `name`   — the framework supplies the answer key (always was overwritten).
- *  - `default`— no resolver uses it; the controller has no preselect concept.
- *  - `filter` — no resolver uses it; transform values in `listItems` instead.
- * (The legacy `SchemaParameterResolver` still honors `default`/`filter`, so the
- * full `PromptConfig` stays for that path.)
- */
-type ResolverPromptConfig = Omit<PromptConfig, "name" | "default" | "filter">;
+ *  - `name`    — the framework supplies the answer key (always was overwritten).
+ *  - `default` — no resolver uses it; the controller has no preselect concept.
+ *  - `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 {
     type: string;
     depends?: readonly string[] | string[];
@@ -571,11 +589,27 @@ interface DynamicResolver extends ResolverBase {
         cursor?: string;
     }) => ListItemsResult<unknown>;
     prompt?: (bag: {
+        /** The CURRENT page's items only — the engine windows the listing one
+         * page at a time (an accumulating host may be showing more). Rendering
+         * input only; validation is the top-level `validate`. */
         items: unknown[];
         input: Record<string, unknown>;
         /** The value `getContext` returned, if any. */
         context?: unknown;
     }) => ResolverPromptConfig;
+    /** Check a chosen/typed value before the engine accepts it. Async with
+     * `imports` so it can verify against the source (`tryResolveFromSearch`'s
+     * sibling for picks) — never against a loaded page: pagination means the
+     * pick can come from a page the engine no longer holds. Return true to
+     * accept or a message to re-ask with. A throw is a lookup failure (the
+     * host gets retry/cancel), not a rejection. */
+    validate?: (bag: {
+        imports: Record<string, unknown>;
+        value: unknown;
+        input: Record<string, unknown>;
+        /** The value `getContext` returned, if any. */
+        context?: unknown;
+    }) => Promise<true | string> | true | string;
     /** Resolve with no user input at all (e.g. a configured default), skipping the
      * prompt. Runs before prompting; used always in non-interactive mode and as a
      * "can we skip asking?" check otherwise. Returns null to fall through to a prompt. */
@@ -726,6 +760,11 @@ interface BoundDynamicResolver extends BoundResolverBase {
         input: Record<string, unknown>;
         context?: unknown;
     }) => ResolverPromptConfig;
+    validate?: (bag: {
+        value: unknown;
+        input: Record<string, unknown>;
+        context?: unknown;
+    }) => Promise<true | string> | true | string;
     tryResolveWithoutPrompt?: (bag: {
         input: Record<string, unknown>;
     }) => Promise<{
@@ -2108,6 +2147,18 @@ declare function defineResolver<const TImports extends ImportsInput = readonly [
         /** The value `getContext` returned, if any. */
         context?: TContext;
     }) => ResolverPromptConfig;
+    /** Check a chosen/typed value before the engine accepts it. Async with
+     * `imports` so it can verify against the source — never against a loaded
+     * page (the pick can come from a page the engine no longer holds). Return
+     * true to accept or a message to re-ask with; a throw is a lookup failure
+     * (retry/cancel), not a rejection. */
+    validate?: (bag: {
+        imports: ImportsOf<TImports>;
+        value: unknown;
+        input: TInput;
+        /** The value `getContext` returned, if any. */
+        context?: TContext;
+    }) => Promise<true | string> | true | string;
     /** Resolve with no user input (e.g. a configured default), skipping the prompt. */
     tryResolveWithoutPrompt?: (bag: {
         imports: ImportsOf<TImports>;
@@ -2741,12 +2792,14 @@ interface ControllerAffordance {
 /** A question the host renders. Discriminated on `type`; the available moves are
  * the self-describing `actions` list (single source of truth, no flags).
  * `actions` is emitted in recommended presentation order — answer directly
- * (`choose`/`custom`/`add`), refine (`search`), paginate (`more`), decline
- * (`skip`/`done`), and failure questions offer `retry` then `cancel` — so a
- * minimal host can render the list verbatim, top to bottom. Hosts with richer
- * widgets (windowed lists, filter state) may reorder. */
+ * (`choose`/`custom`/`add`), refine (`search`), paginate
+ * (`next_page`/`previous_page`), decline (`skip`/`done`), and failure
+ * questions offer `retry` then `cancel` — so a minimal host can render the
+ * list verbatim, top to bottom. Hosts with richer widgets (windowed lists,
+ * filter state) may reorder. */
 type ControllerQuestion = {
     type: "select";
+    path: ControllerPath;
     message: string;
     /** What this field is, for an agent that lacks the schema. */
     description?: string;
@@ -2769,8 +2822,18 @@ type ControllerQuestion = {
      * in its lead-with-term prompt (e.g. "Enter or search app (e.g. 'slack')").
      * Only meaningful before a search has run. */
     placeholder?: string;
+    /** Where these `choices` sit in the paginated listing. `choices` is ONE
+     * page (payloads stay O(page); the engine never re-sends earlier pages).
+     * A window host renders the page and pages with
+     * `next_page`/`previous_page`; an accumulating host appends pages
+     * client-side: same `path` + same `generation` +
+     * advancing `index` means "extend what you showed", and a `generation`
+     * change (a search ran) means "start over". Absent on unpaginated
+     * selects (static enums). */
+    page?: ControllerSelectPage;
 } | {
     type: "input";
+    path: ControllerPath;
     message: string;
     description?: string;
     inputType: "text" | "password" | "email";
@@ -2778,6 +2841,7 @@ type ControllerQuestion = {
     actions: ControllerAffordance[];
 } | {
     type: "collection";
+    path: ControllerPath;
     message: string;
     description?: string;
     /** Which container kind this decision gates. `array` is the add-another
@@ -2806,6 +2870,15 @@ type ControllerQuestion = {
     max?: number;
     actions: ControllerAffordance[];
 };
+/** A select question's position in its paginated listing. */
+interface ControllerSelectPage {
+    /** Increments whenever the listing restarts (a `search` ran, even with the
+     * same term). An accumulating host discards what it has on a new
+     * generation. */
+    generation: number;
+    /** Zero-based page number within this generation. */
+    index: number;
+}
 /** The host's response to a question. The wire shape is frozen: a fuller
  * HATEOAS affordance schema would still produce exactly these. */
 type ControllerAction = {
@@ -2815,7 +2888,9 @@ type ControllerAction = {
     type: "search";
     term: string;
 } | {
-    type: "more";
+    type: "next_page";
+} | {
+    type: "previous_page";
 } | {
     type: "custom";
     value: string;
@@ -2836,7 +2911,7 @@ type ControllerAction = {
 type ControllerResult = {
     status: "ask";
     question: ControllerQuestion;
-    /** The prior answer's validation failure (`PromptConfig.validate`), when
+    /** The prior answer's validation failure (the resolver's `validate`), when
      * this is a re-ask. About the last transition, not the question itself. */
     error?: string;
 } | {
@@ -2889,9 +2964,10 @@ interface ControllerState {
      * 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";
-    /** Listing progress for the current dynamic leaf (serializable: items +
-     * cursor, never a live iterator). */
-    listing?: ControllerListing;
+    /** 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. */
+    pagination?: ControllerPagination;
     /** Whether the host will prompt. Interactive (the default) always asks;
      * non-interactive runs `tryResolveWithoutPrompt` to auto-fill what it can
      * (e.g. configured defaults) before asking for the rest. */
@@ -2900,14 +2976,42 @@ interface ControllerState {
 /** A location in the input tree: top-level `["app"]`, a nested object field
  * `["inputs", "channel"]`, or (later) an array item `["records", 0, "id"]`. */
 type ControllerPath = (string | number)[];
-/** Accumulated candidate items for the current dynamic parameter, plus the
- * serializable cursor for "load more" and the active search term. */
-interface ControllerListing {
-    items: unknown[];
-    cursor?: string;
+/** Where a listing currently stands: the coordinates that make one page of a
+ * dynamic parameter's candidates fetchable — and re-fetchable — with no
+ * shared in-memory state. `previous_page` and `retry` work by re-issuing a
+ * recorded position. */
+interface ControllerListingPosition {
+    /** The active search term, when the resolver is search-mode. */
     search?: string;
-    /** True when the source reported no further pages. */
-    exhausted: boolean;
+    /** Cursor that fetched the current page; `null` is the first page. */
+    pageCursor: string | null;
+    /** Cursors of the pages before this one, oldest first (each entry fetches
+     * that page; `null` is the first page). `previous_page` pops the last. */
+    previousCursors: (string | null)[];
+    /** Increments on every listing restart (each `search`). Surfaced to hosts
+     * via {@link ControllerSelectPage} so accumulators know when to reset. */
+    generation: number;
+}
+/** The enumeration in progress for the current dynamic parameter:
+ * coordinates only. The fetched items ride the ask's `question.choices`; the
+ * host carries back these cursors between steps, never the items it was just
+ * shown. Anything the engine needs to redraw (a validate-rejection re-ask) it
+ * re-fetches statelessly from `position`. */
+interface ControllerPagination {
+    position: ControllerListingPosition;
+    /** Resume point for `next_page`; absent on the last page. */
+    nextCursor?: string;
+    /** The position whose fetch failed, kept so `retry` replays exactly it.
+     * Absent when the page loaded. */
+    retryPosition?: ControllerListingPosition;
+}
+/** One fetched page of a listing: the position it was fetched at plus what
+ * came back. Never stored: `toPagination` strips it to the coordinates the
+ * state keeps. */
+interface ControllerListingPage {
+    position: ControllerListingPosition;
+    items: unknown[];
+    nextCursor?: string;
 }
 /**
  * The one pluggable seam for the in-process `resolve` sugar. It receives the
@@ -3287,30 +3391,55 @@ interface PaginatedResult<TItem> {
     data: TItem[];
     nextCursor?: string;
 }
-type PaginatedSource<TItem> = () => PromiseLike<PaginatedResult<TItem>> & AsyncIterable<PaginatedResult<TItem>>;
 /**
- * Concatenate multiple paginated SDK results into a single paginated stream.
- * Each source is a function returning a dual Promise+AsyncIterable (as SDK
- * paginated methods return). Sources are drained in order.
- *
- * The optional `dedupe` key extractor filters items from source N against
- * all items seen in sources 0 through N-1.
- *
- * Uses paginateBuffered internally to normalize page sizes across source
- * boundaries — e.g. if the first source only has 2 items, they'll be
- * buffered with items from the next source into a full page.
- *
- * Returns the same dual Promise+AsyncIterable shape that resolvers expect.
+ * Supplies one list to `concatLists`: called with that list's own cursor,
+ * resolves one page. An SDK paginated method fits directly
+ * (`({ cursor }) => sdk.listThings({ cursor })`; awaiting a paginated
+ * result yields the requested page).
  */
-declare function concatPaginated<TItem>({ sources, dedupe, pageSize, }: {
-    sources: PaginatedSource<TItem>[];
-    dedupe?: (item: TItem) => string;
+type ListSource<TItem> = (options: {
+    cursor?: string;
+}) => PromiseLike<PaginatedResult<TItem>>;
+/**
+ * List one page of several paginated lists joined end to end. Lists are
+ * drained in order; pass a page's `nextCursor` back in to get the next page.
+ *
+ * Pagination is stateless: every outgoing cursor encodes which list to
+ * resume plus that list's own cursor, so a fresh `concatLists` call
+ * continues exactly where the previous page left off. A cursor stores its
+ * position by list index, so it is only valid while `sources` keeps the
+ * same lists in the same order. Lists must produce disjoint items
+ * themselves; there is no cross-list dedupe (an in-memory seen-set could
+ * not survive the cursor round-trip).
+ *
+ * Uses paginateBuffered internally to normalize page sizes across list
+ * boundaries: if the first list only has 2 items, they'll be buffered with
+ * items from the next list into a full page.
+ */
+declare function concatLists<TItem>({ sources, pageSize, cursor, }: {
+    /** The lists to concatenate, each supplied as a page-fetching source. */
+    sources: ListSource<TItem>[];
     pageSize?: number;
-}): PromiseLike<PaginatedResult<TItem>> & AsyncIterable<PaginatedResult<TItem>>;
+    /** Cursor from a previous `concatLists` page; resumes there. */
+    cursor?: string;
+}): Promise<PaginatedResult<TItem>>;
+/**
+ * @deprecated Use {@link concatLists}; awaiting either yields the same one
+ * page. The page-iterable half of the old return shape is gone; to walk
+ * pages, pass each page's `nextCursor` to a fresh call.
+ */
+declare function concatPaginated<TItem>({ sources, pageSize, cursor, }: {
+    sources: ListSource<TItem>[];
+    pageSize?: number;
+    cursor?: string;
+}): Promise<PaginatedResult<TItem>>;
 /**
  * Strip the PromiseLike from an async iterable, returning a plain
  * AsyncIterable. This prevents async functions from unwrapping the
  * iterable (since async only unwraps PromiseLike, not AsyncIterable).
+ *
+ * @deprecated Call `.pages()` on the paginated result instead; it returns a
+ * plain AsyncIterable over pages with no wrapper needed.
  */
 declare function toIterable<T>(source: AsyncIterable<T>): AsyncIterable<T>;
 
@@ -3395,4 +3524,4 @@ declare class CoreCancelledSignal extends CoreSignal {
     constructor(message?: string);
 }
 
-export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type BoundFormatter, type BoundResolver, CONTEXT, CORE_ERROR_SYMBOL, CORE_OPTIONS_ID, CORE_SIGNAL_SYMBOL, type CategoryDefinition, type ConstantResolver$1 as ConstantResolver, type Controller, type ControllerAction, type ControllerAffordance, type ControllerAnswerFn, type ControllerChoice, type ControllerError, type ControllerIssue, type ControllerListing, type ControllerMethodDescription, type ControllerMethodSummary, type ControllerParameterDescription, type ControllerPath, type ControllerQuestion, type ControllerResult, type ControllerSdk, type ControllerState, type CoreApiError, CoreCancelledSignal, CoreDisposeError, CoreError, CoreErrorCode, type CoreErrorOptions, type CoreOptions, CoreSignal, type CreateSdkOptions, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DisposeFn, type DynamicListResolver, type DynamicMember, type DynamicResolver$1 as DynamicResolver, type DynamicSearchResolver, type FieldsResolver, type FormattedItem, type Formatter, type FunctionDeprecation, type FunctionRegistryEntry, type HookPlugin, type LeafMeta, type LeafSummary, type LegacyMergePlugin, type LegacyPlugin, type ListItemsResult, type ListPromptConfig, type MethodAttachment, type MethodHooks, type MethodOverridePlugin, type MethodPlugin, type MethodScope, type Resolver as ModelResolver, type OnMethodEnd, type OnMethodEndContext, type OnMethodStart, type OnMethodStartContext, type OutputFormatter, type PaginatedSdkFunction, type PaginatedSdkResult, type Plugin, type PluginMeta, type PluginProvides, type PluginStack, type PluginSummary, type PluginSurface, type PositionalMetadata, type PromptConfig, type PromptConfigChoice, type PropertyPlugin, type RegistryResult, type RequiredSdkOf, type Resolver$1 as Resolver, type ResolverConfig, type ResolverFieldItem, type ResolverMetadata, type ResolverPromptConfig, type ResolverType, type Sdk, type SdkContext, type SdkPage, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, composePlugins, concatPaginated, coreOptionsPluginRef, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createValidator, dangerousContextPlugin, declareMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, disposeSdk, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getOutputSchema, getRegistryPlugin, getSchemaDescription, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, resolvePlugin, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };
+export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type BoundFormatter, type BoundResolver, CONTEXT, CORE_ERROR_SYMBOL, CORE_OPTIONS_ID, CORE_SIGNAL_SYMBOL, type CategoryDefinition, type ConstantResolver$1 as ConstantResolver, type Controller, type ControllerAction, type ControllerAffordance, type ControllerAnswerFn, type ControllerChoice, type ControllerError, type ControllerIssue, type ControllerListingPage, type ControllerListingPosition, type ControllerMethodDescription, type ControllerMethodSummary, type ControllerPagination, type ControllerParameterDescription, type ControllerPath, type ControllerQuestion, type ControllerResult, type ControllerSdk, type ControllerSelectPage, type ControllerState, type CoreApiError, CoreCancelledSignal, CoreDisposeError, CoreError, CoreErrorCode, type CoreErrorOptions, type CoreOptions, CoreSignal, type CreateSdkOptions, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DisposeFn, type DynamicListResolver, type DynamicMember, type DynamicResolver$1 as DynamicResolver, type DynamicSearchResolver, type FieldsResolver, type FormattedItem, type Formatter, type FunctionDeprecation, type FunctionRegistryEntry, type HookPlugin, type LeafMeta, type LeafSummary, type LegacyMergePlugin, type LegacyPlugin, type ListItemsResult, type ListPromptConfig, type MethodAttachment, type MethodHooks, type MethodOverridePlugin, type MethodPlugin, type MethodScope, type Resolver as ModelResolver, type OnMethodEnd, type OnMethodEndContext, type OnMethodStart, type OnMethodStartContext, type OutputFormatter, type PaginatedSdkFunction, type PaginatedSdkResult, type Plugin, type PluginMeta, type PluginProvides, type PluginStack, type PluginSummary, type PluginSurface, type PositionalMetadata, type PromptConfig, type PromptConfigChoice, type PropertyPlugin, type RegistryResult, type RequiredSdkOf, type Resolver$1 as Resolver, type ResolverConfig, type ResolverFieldItem, type ResolverMetadata, type ResolverPromptConfig, type ResolverType, type Sdk, type SdkContext, type SdkPage, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, composePlugins, concatLists, concatPaginated, coreOptionsPluginRef, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createValidator, dangerousContextPlugin, declareMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, disposeSdk, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getOutputSchema, getRegistryPlugin, getSchemaDescription, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, resolvePlugin, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };