@zapier/zapier-sdk 0.70.4 → 0.71.0

package/dist/plugins/getConnectionStartUrl/index.d.ts

@@ -0,0 +1,206 @@
+import { type GetConnectionStartUrlItem } from "./schemas";
+export declare const getConnectionStartUrlPlugin: (sdk: {
+    context: {
+        api: import("../..").ApiClient;
+        resolveCredentials: () => Promise<string | {
+            clientId: string;
+            clientSecret: string;
+            type?: "client_credentials" | undefined;
+            baseUrl?: string | undefined;
+            scope?: string | undefined;
+        } | {
+            clientId: string;
+            type?: "pkce" | undefined;
+            baseUrl?: string | undefined;
+            scope?: string | undefined;
+        } | undefined>;
+    };
+} & {
+    context: {
+        getResolvedManifest: () => Promise<import("../manifest").Manifest | null>;
+        getVersionedImplementationId: (appKey: string) => Promise<string | null>;
+        resolveAppKeys: ({ appKeys }: {
+            appKeys: string[];
+        }) => Promise<import("../..").ResolvedAppLocator[]>;
+        updateManifestEntry: (options: import("../manifest").UpdateManifestEntryOptions) => Promise<import("../manifest").UpdateManifestEntryResult>;
+        addActionEntry: (options: import("../manifest").AddActionEntryOptions) => Promise<import("../manifest").AddActionEntryResult>;
+        findActionEntry: ({ name, manifest, }: {
+            name: string;
+            manifest: import("../manifest").Manifest;
+        }) => import("../manifest").ActionEntry | null;
+        listActionEntries: ({ configPath, }?: {
+            configPath?: string;
+        }) => Promise<Array<[string, import("../manifest").ActionEntry]>>;
+        deleteActionEntry: ({ name, configPath, skipWrite, }: {
+            name: string;
+            configPath?: string;
+            skipWrite?: boolean;
+        }) => Promise<import("../manifest").Manifest>;
+        hasActionEntry: ({ name, manifest, }: {
+            name: string;
+            manifest: import("../manifest").Manifest;
+        }) => boolean;
+        findManifestEntry: typeof import("../manifest").findManifestEntry;
+        readManifestFromFile: typeof import("../manifest").readManifestFromFile;
+        getManifestConnections: () => Promise<Record<string, {
+            connectionId: string | number;
+        }> | null>;
+    };
+} & {
+    getApp: (options?: {
+        app: string;
+    } | {
+        appKey: string;
+    } | undefined) => Promise<{
+        data: {
+            slug: string;
+            title: string;
+            key: string;
+            implementation_id: string;
+            description?: string | undefined;
+            is_hidden?: boolean | undefined;
+            auth_type?: string | undefined;
+            actions?: {
+                read?: number | undefined;
+                read_bulk?: number | undefined;
+                write?: number | undefined;
+                search?: number | undefined;
+                search_or_write?: number | undefined;
+                search_and_write?: number | undefined;
+                filter?: number | undefined;
+            } | undefined;
+            is_deprecated?: boolean | undefined;
+            is_beta?: boolean | undefined;
+            is_premium?: boolean | undefined;
+            age_in_days?: number | undefined;
+            banner?: string | undefined;
+            categories?: {
+                id: number;
+                name: string;
+                slug: string;
+            }[] | undefined;
+            images?: {
+                url_16x16?: string | undefined;
+                url_32x32?: string | undefined;
+                url_64x64?: string | undefined;
+                url_128x128?: string | undefined;
+            } | undefined;
+            popularity?: number | undefined;
+            has_filters?: boolean | undefined;
+            has_reads?: boolean | undefined;
+            has_searches?: boolean | undefined;
+            has_searches_or_writes?: boolean | undefined;
+            has_upfront_fields?: boolean | undefined;
+            has_writes?: boolean | undefined;
+            is_built_in?: boolean | undefined;
+            is_featured?: boolean | undefined;
+            is_invite?: boolean | undefined;
+            is_public?: boolean | undefined;
+            is_upcoming?: boolean | undefined;
+            visibility?: string | undefined;
+            primary_color?: string | undefined;
+            secondary_color?: string | undefined;
+            classification?: string | undefined;
+            api_docs_url?: string | undefined;
+            image?: string | undefined;
+            version?: string | undefined;
+        };
+    }>;
+} & {
+    context: {
+        meta: {
+            getApp: import("kitcore").PluginMeta<unknown>;
+        };
+    };
+} & {
+    listApps: (options?: ({
+        search?: string | undefined;
+        apps?: string[] | undefined;
+        appKeys?: string[] | undefined;
+        pageSize?: number | undefined;
+        maxItems?: number | undefined;
+        cursor?: string | undefined;
+    } & {
+        cursor?: string;
+        pageSize?: number;
+        maxItems?: number;
+    }) | undefined) => import("kitcore").PaginatedSdkResult<{
+        slug: string;
+        title: string;
+        key: string;
+        implementation_id: string;
+        description?: string | undefined;
+        is_hidden?: boolean | undefined;
+        auth_type?: string | undefined;
+        actions?: {
+            read?: number | undefined;
+            read_bulk?: number | undefined;
+            write?: number | undefined;
+            search?: number | undefined;
+            search_or_write?: number | undefined;
+            search_and_write?: number | undefined;
+            filter?: number | undefined;
+        } | undefined;
+        is_deprecated?: boolean | undefined;
+        is_beta?: boolean | undefined;
+        is_premium?: boolean | undefined;
+        age_in_days?: number | undefined;
+        banner?: string | undefined;
+        categories?: {
+            id: number;
+            name: string;
+            slug: string;
+        }[] | undefined;
+        images?: {
+            url_16x16?: string | undefined;
+            url_32x32?: string | undefined;
+            url_64x64?: string | undefined;
+            url_128x128?: string | undefined;
+        } | undefined;
+        popularity?: number | undefined;
+        has_filters?: boolean | undefined;
+        has_reads?: boolean | undefined;
+        has_searches?: boolean | undefined;
+        has_searches_or_writes?: boolean | undefined;
+        has_upfront_fields?: boolean | undefined;
+        has_writes?: boolean | undefined;
+        is_built_in?: boolean | undefined;
+        is_featured?: boolean | undefined;
+        is_invite?: boolean | undefined;
+        is_public?: boolean | undefined;
+        is_upcoming?: boolean | undefined;
+        visibility?: string | undefined;
+        primary_color?: string | undefined;
+        secondary_color?: string | undefined;
+        classification?: string | undefined;
+        api_docs_url?: string | undefined;
+        image?: string | undefined;
+        version?: string | undefined;
+    }>;
+} & {
+    context: {
+        meta: {
+            listApps: import("kitcore").PluginMeta<unknown>;
+        };
+    };
+} & {
+    context: import("../eventEmission").EventEmissionContext;
+} & {
+    context: {
+        meta: Record<string, import("kitcore").PluginMeta>;
+    };
+}) => {
+    getConnectionStartUrl: (options?: {
+        app: string;
+    } | undefined) => Promise<{
+        data: GetConnectionStartUrlItem;
+    }>;
+} & {
+    context: {
+        meta: {
+            getConnectionStartUrl: import("kitcore").PluginMeta<unknown>;
+        };
+    };
+};
+export type GetConnectionStartUrlPluginProvides = ReturnType<typeof getConnectionStartUrlPlugin>;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/getConnectionStartUrl/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/getConnectionStartUrl/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,WAAW,CAAC;AAoBnB,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAmDuhX,CAAC;;;;sBAAiX,CAAC;qBAAyB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cApCp7X,yBAAyB;;;;;;;;CA+BhD,CAAC;AAEF,MAAM,MAAM,mCAAmC,GAAG,UAAU,CAC1D,OAAO,2BAA2B,CACnC,CAAC"}

package/dist/plugins/getConnectionStartUrl/index.js

@@ -0,0 +1,39 @@
+import { definePlugin, createPluginMethod } from "kitcore";
+import { setMethodMetadata } from "../eventEmission/method-metadata";
+import { appKeyResolver } from "../../resolvers";
+import { GetConnectionStartUrlSchema, GetConnectionStartUrlItemSchema, } from "./schemas";
+// Server endpoint that mints a signed, single-use connection start URL.
+const START_PATH = "/zapier/api/authentications/v1/sdk/connections/start";
+export const getConnectionStartUrlPlugin = definePlugin((sdk) => createPluginMethod(sdk, {
+    name: "getConnectionStartUrl",
+    categories: ["connection"],
+    type: "create",
+    itemType: "ConnectionStartUrl",
+    inputSchema: GetConnectionStartUrlSchema,
+    outputSchema: GetConnectionStartUrlItemSchema,
+    resolvers: { app: appKeyResolver },
+    handler: async ({ sdk: inner, options, }) => {
+        // Send the versionless app key: the server resolves it to the freshest
+        // production version when the user opens the URL, which can be minutes
+        // after this call.
+        const versionedKey = await inner.context.getVersionedImplementationId(options.app);
+        const selectedApi = versionedKey
+            ? versionedKey.split("@")[0]
+            : options.app;
+        // Tag this method's scope so eventEmission's onMethodEnd hook
+        // emits the MethodCalled event with `selected_api` set.
+        setMethodMetadata({ selectedApi });
+        const response = await inner.context.api.post(START_PATH, { selected_api: selectedApi }, { authRequired: true });
+        // Parse the mapped shape against the output schema so a server-side
+        // response change surfaces as a validation error here rather than
+        // silently producing a malformed item.
+        return {
+            data: GetConnectionStartUrlItemSchema.parse({
+                url: response.url,
+                expiresAt: response.expires_at,
+                startedAt: response.started_at,
+                app: selectedApi,
+            }),
+        };
+    },
+}));

package/dist/plugins/getConnectionStartUrl/schemas.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export declare const GetConnectionStartUrlSchema: z.ZodObject<{
+    app: z.ZodString & {
+        _def: z.core.$ZodStringDef & import("kitcore").PositionalMetadata;
+    };
+}, z.core.$strip>;
+export type GetConnectionStartUrlOptions = z.infer<typeof GetConnectionStartUrlSchema>;
+export declare const GetConnectionStartUrlItemSchema: z.ZodObject<{
+    url: z.ZodString;
+    expiresAt: z.ZodNumber;
+    startedAt: z.ZodNumber;
+    app: z.ZodString;
+}, z.core.$strip>;
+export type GetConnectionStartUrlItem = z.infer<typeof GetConnectionStartUrlItemSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/plugins/getConnectionStartUrl/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/plugins/getConnectionStartUrl/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,2BAA2B;;;;iBAMrC,CAAC;AAEJ,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,2BAA2B,CACnC,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;iBAyBzC,CAAC;AAEJ,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,+BAA+B,CACvC,CAAC"}

package/dist/plugins/getConnectionStartUrl/schemas.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { AppPropertySchema } from "../../types/properties";
+export const GetConnectionStartUrlSchema = z
+    .object({
+    app: AppPropertySchema,
+})
+    .describe("Mint a short-lived URL that begins an SDK-initiated connection flow. The URL is signed by zapier.com and bound to the current user/account — opening it in a different browser session will fail the binding check. Returns the URL as data so the caller decides what to do with it.\n\nUse this directly (rather than the higher-level `create-connection`) when you want either of: (a) hand off the URL and *not* block waiting for completion — call this alone, skip `wait-for-new-connection` entirely, or (b) do something custom between minting the URL and waiting for the connection — call this, then email or DM the URL, render it as a QR code for mobile sign-in, etc., then call `wait-for-new-connection`. For the common case where you'd just print and poll back-to-back, `create-connection` is one call.\n\nPair with `wait-for-new-connection` to detect completion: pass the `startedAt` returned here straight through (it's the server's mint time, so polling isn't affected by client clock skew). Example (JS):\n\n```ts\nconst { data: { url, app, startedAt } } = await zapier.getConnectionStartUrl({ app: 'slack' });\n// hand `url` off — print it, DM it, email it, render a button, whatever\nconst { data: conn } = await zapier.waitForNewConnection({ app, startedAt });\n```");
+export const GetConnectionStartUrlItemSchema = z
+    .object({
+    url: z
+        .string()
+        .describe("URL the user should open in their browser to complete the auth flow. Single-use, time-limited."),
+    expiresAt: z
+        .number()
+        .describe("Unix timestamp (seconds) after which the URL's signature is rejected by zapier.com."),
+    startedAt: z
+        .number()
+        .describe("Unix timestamp (seconds) when the server minted the URL. Use it as the `startedAt` for `wait-for-new-connection` so polling is anchored to server time rather than a possibly-skewed client clock."),
+    app: z
+        .string()
+        .describe("Versionless app key the URL was minted for (e.g., 'SlackCLIAPI'). Useful for downstream filtering."),
+})
+    .describe("The signed start-URL plus metadata needed to poll for completion.");

package/dist/plugins/waitForNewConnection/index.d.ts

@@ -0,0 +1,209 @@
+import { type WaitForNewConnectionItem } from "./schemas";
+export declare const waitForNewConnectionPlugin: (sdk: {
+    context: {
+        api: import("../..").ApiClient;
+        resolveCredentials: () => Promise<string | {
+            clientId: string;
+            clientSecret: string;
+            type?: "client_credentials" | undefined;
+            baseUrl?: string | undefined;
+            scope?: string | undefined;
+        } | {
+            clientId: string;
+            type?: "pkce" | undefined;
+            baseUrl?: string | undefined;
+            scope?: string | undefined;
+        } | undefined>;
+    };
+} & {
+    context: {
+        getResolvedManifest: () => Promise<import("../manifest").Manifest | null>;
+        getVersionedImplementationId: (appKey: string) => Promise<string | null>;
+        resolveAppKeys: ({ appKeys }: {
+            appKeys: string[];
+        }) => Promise<import("../..").ResolvedAppLocator[]>;
+        updateManifestEntry: (options: import("../manifest").UpdateManifestEntryOptions) => Promise<import("../manifest").UpdateManifestEntryResult>;
+        addActionEntry: (options: import("../manifest").AddActionEntryOptions) => Promise<import("../manifest").AddActionEntryResult>;
+        findActionEntry: ({ name, manifest, }: {
+            name: string;
+            manifest: import("../manifest").Manifest;
+        }) => import("../manifest").ActionEntry | null;
+        listActionEntries: ({ configPath, }?: {
+            configPath?: string;
+        }) => Promise<Array<[string, import("../manifest").ActionEntry]>>;
+        deleteActionEntry: ({ name, configPath, skipWrite, }: {
+            name: string;
+            configPath?: string;
+            skipWrite?: boolean;
+        }) => Promise<import("../manifest").Manifest>;
+        hasActionEntry: ({ name, manifest, }: {
+            name: string;
+            manifest: import("../manifest").Manifest;
+        }) => boolean;
+        findManifestEntry: typeof import("../manifest").findManifestEntry;
+        readManifestFromFile: typeof import("../manifest").readManifestFromFile;
+        getManifestConnections: () => Promise<Record<string, {
+            connectionId: string | number;
+        }> | null>;
+    };
+} & {
+    getApp: (options?: {
+        app: string;
+    } | {
+        appKey: string;
+    } | undefined) => Promise<{
+        data: {
+            slug: string;
+            title: string;
+            key: string;
+            implementation_id: string;
+            description?: string | undefined;
+            is_hidden?: boolean | undefined;
+            auth_type?: string | undefined;
+            actions?: {
+                read?: number | undefined;
+                read_bulk?: number | undefined;
+                write?: number | undefined;
+                search?: number | undefined;
+                search_or_write?: number | undefined;
+                search_and_write?: number | undefined;
+                filter?: number | undefined;
+            } | undefined;
+            is_deprecated?: boolean | undefined;
+            is_beta?: boolean | undefined;
+            is_premium?: boolean | undefined;
+            age_in_days?: number | undefined;
+            banner?: string | undefined;
+            categories?: {
+                id: number;
+                name: string;
+                slug: string;
+            }[] | undefined;
+            images?: {
+                url_16x16?: string | undefined;
+                url_32x32?: string | undefined;
+                url_64x64?: string | undefined;
+                url_128x128?: string | undefined;
+            } | undefined;
+            popularity?: number | undefined;
+            has_filters?: boolean | undefined;
+            has_reads?: boolean | undefined;
+            has_searches?: boolean | undefined;
+            has_searches_or_writes?: boolean | undefined;
+            has_upfront_fields?: boolean | undefined;
+            has_writes?: boolean | undefined;
+            is_built_in?: boolean | undefined;
+            is_featured?: boolean | undefined;
+            is_invite?: boolean | undefined;
+            is_public?: boolean | undefined;
+            is_upcoming?: boolean | undefined;
+            visibility?: string | undefined;
+            primary_color?: string | undefined;
+            secondary_color?: string | undefined;
+            classification?: string | undefined;
+            api_docs_url?: string | undefined;
+            image?: string | undefined;
+            version?: string | undefined;
+        };
+    }>;
+} & {
+    context: {
+        meta: {
+            getApp: import("kitcore").PluginMeta<unknown>;
+        };
+    };
+} & {
+    listApps: (options?: ({
+        search?: string | undefined;
+        apps?: string[] | undefined;
+        appKeys?: string[] | undefined;
+        pageSize?: number | undefined;
+        maxItems?: number | undefined;
+        cursor?: string | undefined;
+    } & {
+        cursor?: string;
+        pageSize?: number;
+        maxItems?: number;
+    }) | undefined) => import("kitcore").PaginatedSdkResult<{
+        slug: string;
+        title: string;
+        key: string;
+        implementation_id: string;
+        description?: string | undefined;
+        is_hidden?: boolean | undefined;
+        auth_type?: string | undefined;
+        actions?: {
+            read?: number | undefined;
+            read_bulk?: number | undefined;
+            write?: number | undefined;
+            search?: number | undefined;
+            search_or_write?: number | undefined;
+            search_and_write?: number | undefined;
+            filter?: number | undefined;
+        } | undefined;
+        is_deprecated?: boolean | undefined;
+        is_beta?: boolean | undefined;
+        is_premium?: boolean | undefined;
+        age_in_days?: number | undefined;
+        banner?: string | undefined;
+        categories?: {
+            id: number;
+            name: string;
+            slug: string;
+        }[] | undefined;
+        images?: {
+            url_16x16?: string | undefined;
+            url_32x32?: string | undefined;
+            url_64x64?: string | undefined;
+            url_128x128?: string | undefined;
+        } | undefined;
+        popularity?: number | undefined;
+        has_filters?: boolean | undefined;
+        has_reads?: boolean | undefined;
+        has_searches?: boolean | undefined;
+        has_searches_or_writes?: boolean | undefined;
+        has_upfront_fields?: boolean | undefined;
+        has_writes?: boolean | undefined;
+        is_built_in?: boolean | undefined;
+        is_featured?: boolean | undefined;
+        is_invite?: boolean | undefined;
+        is_public?: boolean | undefined;
+        is_upcoming?: boolean | undefined;
+        visibility?: string | undefined;
+        primary_color?: string | undefined;
+        secondary_color?: string | undefined;
+        classification?: string | undefined;
+        api_docs_url?: string | undefined;
+        image?: string | undefined;
+        version?: string | undefined;
+    }>;
+} & {
+    context: {
+        meta: {
+            listApps: import("kitcore").PluginMeta<unknown>;
+        };
+    };
+} & {
+    context: import("../eventEmission").EventEmissionContext;
+} & {
+    context: {
+        meta: Record<string, import("kitcore").PluginMeta>;
+    };
+}) => {
+    waitForNewConnection: (options?: {
+        app: string;
+        startedAt: number;
+        timeoutMs?: number | undefined;
+        pollIntervalMs?: number | undefined;
+    } | undefined) => Promise<{
+        data: WaitForNewConnectionItem;
+    }>;
+} & {
+    context: {
+        meta: {
+            waitForNewConnection: import("kitcore").PluginMeta<unknown>;
+        };
+    };
+};
+export type WaitForNewConnectionPluginProvides = ReturnType<typeof waitForNewConnectionPlugin>;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/waitForNewConnection/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/waitForNewConnection/index.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,WAAW,CAAC;AAuBnB,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAwFuwT,CAAC;;;;sBAAiX,CAAC;qBAAyB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAzEnqU,wBAAwB;;;;;;;;CAoE/C,CAAC;AAEF,MAAM,MAAM,kCAAkC,GAAG,UAAU,CACzD,OAAO,0BAA0B,CAClC,CAAC"}

package/dist/plugins/waitForNewConnection/index.js

@@ -0,0 +1,75 @@
+import { definePlugin, createPluginMethod } from "kitcore";
+import { setMethodMetadata } from "../eventEmission/method-metadata";
+import { appKeyResolver } from "../../resolvers";
+import { ZapierTimeoutError } from "../../types/errors";
+import { WaitForNewConnectionSchema, WaitForNewConnectionItemSchema, } from "./schemas";
+const CONNECTIONS_PATH = "/api/v0/connections";
+export const waitForNewConnectionPlugin = definePlugin((sdk) => createPluginMethod(sdk, {
+    name: "waitForNewConnection",
+    categories: ["connection"],
+    type: "item",
+    itemType: "Connection",
+    inputSchema: WaitForNewConnectionSchema,
+    outputSchema: WaitForNewConnectionItemSchema,
+    resolvers: { app: appKeyResolver },
+    handler: async ({ sdk: inner, options, }) => {
+        // Resolve slug → versionless app key so the `app_key` filter matches
+        // what the API stores on connection rows.
+        const versionedKey = await inner.context.getVersionedImplementationId(options.app);
+        const appKey = versionedKey ? versionedKey.split("@")[0] : options.app;
+        // Tag this method's scope so eventEmission's onMethodEnd hook
+        // emits the MethodCalled event with `selected_api` set.
+        setMethodMetadata({ selectedApi: appKey });
+        // Server-side sort newest-first + `page_size=1` lets us poll a one-row
+        // response and just check the head: if the most recently created
+        // `appKey` connection is fresh (`date >= startedAt`), it's ours by
+        // construction. No pagination concerns; no client-side disambiguation
+        // among fresh rows. Delegating the poll loop to `api.poll` also gets
+        // us backoff, timeout enforcement, and consistent `ZapierTimeoutError`
+        // behavior for free.
+        try {
+            const top = await inner.context.api.poll(CONNECTIONS_PATH, {
+                searchParams: {
+                    app_key: appKey,
+                    // Scope to the current user's own connections. The connection
+                    // we're waiting on is by definition owned by the caller; without
+                    // this the one-row head-check could match a teammate's freshly
+                    // created connection for the same app.
+                    owner: "me",
+                    is_expired: "false",
+                    ordering: "-date",
+                    page_size: "1",
+                },
+                authRequired: true,
+                timeoutMs: options.timeoutMs ?? 300000,
+                initialDelay: options.pollIntervalMs ?? 3000,
+                isPending: (body) => {
+                    const rows = body.data ?? [];
+                    const head = rows[0];
+                    if (!head?.date)
+                        return true;
+                    const created = Math.floor(new Date(head.date).getTime() / 1000);
+                    return !Number.isFinite(created) || created < options.startedAt;
+                },
+                resultExtractor: (body) => 
+                // `isPending` guaranteed a fresh row at index 0 before this fires.
+                body.data[0],
+            });
+            return {
+                data: WaitForNewConnectionItemSchema.parse({
+                    id: String(top.public_id ?? top.id),
+                    app: appKey,
+                    title: top.title ?? null,
+                }),
+            };
+        }
+        catch (err) {
+            // Wrap api.poll's generic timeout with an actionable next step.
+            if (err instanceof ZapierTimeoutError) {
+                throw new ZapierTimeoutError(`Timed out waiting for a new "${appKey}" connection. ` +
+                    `If the user completed the auth flow, retrieve the connection via sdk.getConnection({ id }) with the ID shown on the completion page.`);
+            }
+            throw err;
+        }
+    },
+}));

package/dist/plugins/waitForNewConnection/schemas.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export declare const WaitForNewConnectionSchema: z.ZodObject<{
+    app: z.ZodString & {
+        _def: z.core.$ZodStringDef & import("kitcore").PositionalMetadata;
+    };
+    startedAt: z.ZodNumber;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    pollIntervalMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type WaitForNewConnectionOptions = z.infer<typeof WaitForNewConnectionSchema>;
+export declare const WaitForNewConnectionItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    app: z.ZodString;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type WaitForNewConnectionItem = z.infer<typeof WaitForNewConnectionItemSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/plugins/waitForNewConnection/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/plugins/waitForNewConnection/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,0BAA0B;;;;;;;iBA6BpC,CAAC;AAEJ,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,0BAA0B,CAClC,CAAC;AAEF,eAAO,MAAM,8BAA8B;;;;iBAoBS,CAAC;AAErD,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAC5C,OAAO,8BAA8B,CACtC,CAAC"}

package/dist/plugins/waitForNewConnection/schemas.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { AppPropertySchema } from "../../types/properties";
+export const WaitForNewConnectionSchema = z
+    .object({
+    app: AppPropertySchema,
+    startedAt: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("Unix timestamp (seconds). Only connections whose `date` is at or after this value count as 'new'. Prefer the `startedAt` returned by `get-connection-start-url` — it's server-stamped, so the comparison isn't thrown off by client clock skew. If you mint the timestamp yourself, capture it *before* showing the start URL so a fast OAuth completion isn't missed."),
+    timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("How long to wait before giving up. Default 5 minutes (300_000)."),
+    pollIntervalMs: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Delay before the first poll request, in ms. Default 3 seconds (3_000). Subsequent polling cadence is managed by the SDK's polling primitive (backoff with sane defaults)."),
+})
+    .describe("Wait for a new connection to appear for the given app. Polls `/api/v0/connections` with server-side `ordering=-date` until the most recent matching row's `date` is at or after the started-at timestamp, then returns it. Pair with `get-connection-start-url` — that mints the URL the user opens, this waits for the resulting connection to land. Errors with a timeout after the configured timeout (default 5 min). Example (JS):\n\n```ts\nconst { data: { url, app, startedAt } } = await zapier.getConnectionStartUrl({ app: 'slack' });\n// show `url` to the user via the channel they're reading from\nconst { data: conn } = await zapier.waitForNewConnection({ app, startedAt });\n```");
+export const WaitForNewConnectionItemSchema = z
+    .object({
+    id: z
+        .string()
+        .describe("The new connection's ID. Public UUID when available, falling back to the numeric ID."),
+    app: z
+        .string()
+        .describe("Versionless app key the connection was created for (e.g., 'SlackCLIAPI')."),
+    title: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Human-readable connection title set by the auth flow, when available."),
+})
+    .describe("The new connection that was detected.");