@automate.ax/integration-contracts 0.147.1 → 0.148.0

package/dist/close/events.d.ts

@@ -487,9 +487,9 @@ export declare const closeTriggerContracts: {
                     error: "error";
                     draft: "draft";
                     sent: "sent";
+                    scheduled: "scheduled";
                     inbox: "inbox";
                     outbox: "outbox";
-                    scheduled: "scheduled";
                 }>>;
                 subject: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 templateId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -575,9 +575,9 @@ export declare const closeTriggerContracts: {
                     error: "error";
                     draft: "draft";
                     sent: "sent";
+                    scheduled: "scheduled";
                     inbox: "inbox";
                     outbox: "outbox";
-                    scheduled: "scheduled";
                 }>>;
                 subject: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 templateId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -2162,9 +2162,9 @@ export declare const closeTriggerContracts: {
                     error: "error";
                     draft: "draft";
                     sent: "sent";
+                    scheduled: "scheduled";
                     inbox: "inbox";
                     outbox: "outbox";
-                    scheduled: "scheduled";
                 }>>;
                 templateId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -2233,9 +2233,9 @@ export declare const closeTriggerContracts: {
                     error: "error";
                     draft: "draft";
                     sent: "sent";
+                    scheduled: "scheduled";
                     inbox: "inbox";
                     outbox: "outbox";
-                    scheduled: "scheduled";
                 }>>;
                 templateId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 text: z.ZodOptional<z.ZodNullable<z.ZodString>>;

package/dist/close/schemas.d.ts

@@ -907,9 +907,9 @@ export declare const CLOSE_EMAIL_SCHEMA: z.ZodObject<{
         error: "error";
         draft: "draft";
         sent: "sent";
+        scheduled: "scheduled";
         inbox: "inbox";
         outbox: "outbox";
-        scheduled: "scheduled";
     }>;
     subject: z.ZodNullable<z.ZodString>;
     templateId: z.ZodNullable<z.ZodString>;
@@ -962,9 +962,9 @@ export declare const CLOSE_SMS_SCHEMA: z.ZodObject<{
         error: "error";
         draft: "draft";
         sent: "sent";
+        scheduled: "scheduled";
         inbox: "inbox";
         outbox: "outbox";
-        scheduled: "scheduled";
     }>;
     templateId: z.ZodNullable<z.ZodString>;
     text: z.ZodNullable<z.ZodString>;
@@ -1129,9 +1129,9 @@ export declare const CLOSE_ACTIVITY_SCHEMA: z.ZodDiscriminatedUnion<[z.ZodObject
         error: "error";
         draft: "draft";
         sent: "sent";
+        scheduled: "scheduled";
         inbox: "inbox";
         outbox: "outbox";
-        scheduled: "scheduled";
     }>;
     subject: z.ZodNullable<z.ZodString>;
     templateId: z.ZodNullable<z.ZodString>;
@@ -1271,9 +1271,9 @@ export declare const CLOSE_ACTIVITY_SCHEMA: z.ZodDiscriminatedUnion<[z.ZodObject
         error: "error";
         draft: "draft";
         sent: "sent";
+        scheduled: "scheduled";
         inbox: "inbox";
         outbox: "outbox";
-        scheduled: "scheduled";
     }>;
     templateId: z.ZodNullable<z.ZodString>;
     text: z.ZodNullable<z.ZodString>;
@@ -1411,9 +1411,9 @@ export declare const CLOSE_ACTIVITY_SCHEMA: z.ZodDiscriminatedUnion<[z.ZodObject
             error: "error";
             draft: "draft";
             sent: "sent";
+            scheduled: "scheduled";
             inbox: "inbox";
             outbox: "outbox";
-            scheduled: "scheduled";
         }>;
         subject: z.ZodNullable<z.ZodString>;
         templateId: z.ZodNullable<z.ZodString>;
@@ -1507,9 +1507,9 @@ export declare const CLOSE_ACTIVITY_SCHEMA: z.ZodDiscriminatedUnion<[z.ZodObject
             error: "error";
             draft: "draft";
             sent: "sent";
+            scheduled: "scheduled";
             inbox: "inbox";
             outbox: "outbox";
-            scheduled: "scheduled";
         }>;
         subject: z.ZodNullable<z.ZodString>;
         to: z.ZodArray<z.ZodString>;

package/dist/google-drive/index.d.ts

@@ -45,6 +45,7 @@ export declare const GOOGLE_DRIVE_EVENT_SCHEMA: z.ZodObject<{
         completed: "completed";
         deleted: "deleted";
         resolved: "resolved";
+        trashed: "trashed";
         moved: "moved";
         contentChanged: "contentChanged";
         edited: "edited";
@@ -53,7 +54,6 @@ export declare const GOOGLE_DRIVE_EVENT_SCHEMA: z.ZodObject<{
         reset: "reset";
         responded: "responded";
         reviewersChanged: "reviewersChanged";
-        trashed: "trashed";
         untrashed: "untrashed";
     }>;
     assigneeEmailAddress: z.ZodOptional<z.ZodEmail>;
@@ -959,6 +959,7 @@ export declare const googleDriveTriggerContracts: {
                 completed: "completed";
                 deleted: "deleted";
                 resolved: "resolved";
+                trashed: "trashed";
                 moved: "moved";
                 contentChanged: "contentChanged";
                 edited: "edited";
@@ -967,7 +968,6 @@ export declare const googleDriveTriggerContracts: {
                 reset: "reset";
                 responded: "responded";
                 reviewersChanged: "reviewersChanged";
-                trashed: "trashed";
                 untrashed: "untrashed";
             }>;
             assigneeEmailAddress: z.ZodOptional<z.ZodEmail>;
@@ -1038,7 +1038,7 @@ export declare function toGoogleDriveTriggerType(providerEventType: string): Goo
  * @param eventType - Stable internal semantic event type.
  */
 export declare function parseGoogleDriveTriggerType(eventType: GoogleDriveTriggerType): {
-    action: "created" | "cancelled" | "completed" | "deleted" | "resolved" | "moved" | "contentChanged" | "edited" | "reopened" | "renamed" | "reset" | "responded" | "reviewersChanged" | "trashed" | "untrashed";
+    action: "created" | "cancelled" | "completed" | "deleted" | "resolved" | "trashed" | "moved" | "contentChanged" | "edited" | "reopened" | "renamed" | "reset" | "responded" | "reviewersChanged" | "untrashed";
     resourceType: "file" | "comment" | "reply" | "accessProposal" | "approval" | "permission";
 };
 export {};

package/dist/kit/api.d.ts

@@ -0,0 +1,78 @@
+import { type Encodable } from "@automate.ax/codec";
+import type { KitOperationKey } from "./operation-manifest.js";
+import type { KitOperationInput, KitOperationOutput } from "./types.js";
+/** Resolved account accepted by the shared Kit API client. */
+export interface KitResolvedAccount {
+    connectionMethodId: string;
+    secret: Record<string, unknown>;
+    serviceId: "kit";
+}
+/** Options for an internal provider-native Kit request. */
+export interface KitRequestOptions {
+    body?: Encodable;
+    method?: "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+    query?: Record<string, boolean | number | string | (boolean | number | string)[] | null | undefined>;
+}
+/** Structured error returned by a rejected Kit request. */
+export declare class KitApiError extends Error {
+    readonly body?: Encodable;
+    readonly retryAfter?: string;
+    readonly status: number;
+    /**
+     * Creates a structured provider error.
+     *
+     * @param options Error properties.
+     * @param options.body Parsed provider response body.
+     * @param options.retryAfter Provider retry guidance.
+     * @param options.status HTTP status code.
+     */
+    constructor(options: {
+        body?: Encodable;
+        retryAfter?: string;
+        status: number;
+    });
+}
+/**
+ * Creates an authenticated Kit V4 API client.
+ *
+ * @param account Resolved Kit account.
+ */
+export declare function getKitApi(account: KitResolvedAccount): {
+    /**
+     * Executes and validates one named public Kit operation.
+     *
+     * @param key Public operation name.
+     * @param input Flattened operation input.
+     */
+    operation<TKey extends KitOperationKey>(key: TKey, input: KitOperationInput<TKey>): Promise<KitOperationOutput<TKey>>;
+    /**
+     * Sends an internal provider-native request used for managed webhooks.
+     *
+     * This is not exposed as an automation action.
+     *
+     * @param path Provider-relative Kit V4 path.
+     * @param options Request options.
+     */
+    requestJson(path: string, options?: KitRequestOptions): Promise<unknown>;
+};
+/**
+ * Encodes every interpolation as one Kit URL path segment.
+ *
+ * @param strings Template string segments.
+ * @param values Interpolated path values.
+ */
+export declare function kitPath(strings: TemplateStringsArray, ...values: (number | string)[]): string;
+/**
+ * Converts public camelCase fields to documented Kit wire fields.
+ *
+ * @param value Public value.
+ * @param schema Provider wire schema.
+ */
+export declare function kitPublicToWire(value: unknown, schema: Record<string, unknown>): Encodable;
+/**
+ * Converts documented Kit wire fields to public camelCase fields.
+ *
+ * @param value Provider value.
+ * @param schema Provider wire schema.
+ */
+export declare function kitWireToPublic(value: unknown, schema: Record<string, unknown>): Encodable;

package/dist/kit/api.js

@@ -0,0 +1,386 @@
+import { encodableSchema } from "@automate.ax/codec";
+import * as z from "zod";
+import { KIT_WIRE_DEFINITIONS, kitOperation, kitOperationOutputSchema, } from "./schemas.js";
+const KIT_API_BASE_URL = "https://api.kit.com/v4/";
+const KIT_API_ORIGIN = new URL(KIT_API_BASE_URL).origin;
+const KIT_API_KEY_SECRET_SCHEMA = z.object({
+    apiKey: z.string().trim().min(1),
+});
+const KIT_OAUTH_SECRET_SCHEMA = z.object({
+    accessToken: z.string().trim().min(1),
+});
+/** Structured error returned by a rejected Kit request. */
+export class KitApiError extends Error {
+    body;
+    retryAfter;
+    status;
+    /**
+     * Creates a structured provider error.
+     *
+     * @param options Error properties.
+     * @param options.body Parsed provider response body.
+     * @param options.retryAfter Provider retry guidance.
+     * @param options.status HTTP status code.
+     */
+    constructor(options) {
+        super(getErrorMessage(options.body) ??
+            `Kit API request failed with status ${options.status}.`);
+        this.name = "KitApiError";
+        this.body = options.body;
+        this.retryAfter = options.retryAfter;
+        this.status = options.status;
+    }
+}
+/**
+ * Creates an authenticated Kit V4 API client.
+ *
+ * @param account Resolved Kit account.
+ */
+export function getKitApi(account) {
+    const authorization = getAuthorization(account);
+    return {
+        /**
+         * Executes and validates one named public Kit operation.
+         *
+         * @param key Public operation name.
+         * @param input Flattened operation input.
+         */
+        async operation(key, input) {
+            const definition = kitOperation(key);
+            const inputRecord = input;
+            // Build the path before request assembly so every interpolation is encoded.
+            const path = definition.path
+                .replace(/^\/v4\//, "")
+                .replace(/\{([^}]+)\}/g, (_match, providerName) => {
+                const parameter = definition.pathParameters.find((candidate) => candidate.providerName === providerName);
+                if (!parameter) {
+                    throw new TypeError(`Unknown Kit path parameter: ${providerName}`);
+                }
+                return encodePathSegment(inputRecord[parameter.name], parameter.name);
+            });
+            // Preserve undefined query fields for the shared serializer to omit.
+            const query = Object.fromEntries(definition.queryParameters.map((parameter) => [
+                parameter.providerName,
+                parseQueryValue(inputRecord[parameter.name]),
+            ]));
+            const body = Object.fromEntries(definition.bodyParameters.flatMap((name) => inputRecord[name] === undefined ? [] : [[name, inputRecord[name]]]));
+            const parsed = await sendKitRequest(authorization, path, {
+                ...(definition.bodyParameters.length > 0 && {
+                    body: kitPublicToWire(body, definition.bodyWireSchema ?? {}),
+                }),
+                method: definition.method,
+                query,
+            });
+            // Normalize provider fields before validating the public return type.
+            const output = definition.responseMode === "void"
+                ? {}
+                : kitWireToPublic(parsed, definition.outputWireSchema);
+            return kitOperationOutputSchema(key).parse(output);
+        },
+        /**
+         * Sends an internal provider-native request used for managed webhooks.
+         *
+         * This is not exposed as an automation action.
+         *
+         * @param path Provider-relative Kit V4 path.
+         * @param options Request options.
+         */
+        async requestJson(path, options = {}) {
+            return await sendKitRequest(authorization, path, options);
+        },
+    };
+}
+/**
+ * Encodes every interpolation as one Kit URL path segment.
+ *
+ * @param strings Template string segments.
+ * @param values Interpolated path values.
+ */
+export function kitPath(strings, ...values) {
+    return strings.reduce((path, part, index) => `${path}${index === 0 ? "" : encodeURIComponent(String(values[index - 1]))}${part}`, "");
+}
+/**
+ * Converts public camelCase fields to documented Kit wire fields.
+ *
+ * @param value Public value.
+ * @param schema Provider wire schema.
+ */
+export function kitPublicToWire(value, schema) {
+    return encodableSchema.parse(transformKitValue(value, schema, "toWire"));
+}
+/**
+ * Converts documented Kit wire fields to public camelCase fields.
+ *
+ * @param value Provider value.
+ * @param schema Provider wire schema.
+ */
+export function kitWireToPublic(value, schema) {
+    return encodableSchema.parse(transformKitValue(value, schema, "toPublic"));
+}
+/**
+ * Returns the authorization header for a resolved Kit account.
+ *
+ * @param account Resolved Kit account.
+ * @throws When the connection method is unsupported.
+ */
+function getAuthorization(account) {
+    if (account.connectionMethodId === "oauth") {
+        return {
+            Authorization: `Bearer ${KIT_OAUTH_SECRET_SCHEMA.parse(account.secret).accessToken}`,
+        };
+    }
+    if (account.connectionMethodId === "api-key") {
+        return {
+            "X-Kit-Api-Key": KIT_API_KEY_SECRET_SCHEMA.parse(account.secret).apiKey,
+        };
+    }
+    throw new Error(`Unsupported Kit connection method: ${account.connectionMethodId}`);
+}
+/**
+ * Sends one guarded request to the Kit V4 API.
+ *
+ * @param authorization Authentication headers.
+ * @param path Provider-relative API path.
+ * @param options Request options.
+ */
+async function sendKitRequest(authorization, path, options) {
+    const normalizedPath = path.replace(/^\/+/, "");
+    const url = new URL(normalizedPath, KIT_API_BASE_URL);
+    if (!normalizedPath ||
+        normalizedPath.includes("://") ||
+        normalizedPath.includes("\\") ||
+        normalizedPath.includes("?") ||
+        normalizedPath.includes("#") ||
+        url.origin !== KIT_API_ORIGIN ||
+        !url.pathname.startsWith(new URL(KIT_API_BASE_URL).pathname)) {
+        throw new TypeError("Kit API paths must remain provider-relative.");
+    }
+    for (const [name, value] of Object.entries(options.query ?? {})) {
+        appendQuery(url, { explode: true, name, providerName: name, style: "form" }, value);
+    }
+    const response = await fetch(url, {
+        body: options.body === undefined ? undefined : JSON.stringify(options.body),
+        headers: {
+            Accept: "application/json",
+            ...authorization,
+            ...(options.body === undefined
+                ? {}
+                : { "Content-Type": "application/json" }),
+        },
+        method: options.method ?? "GET",
+        redirect: "error",
+    });
+    const parsed = await parseResponse(response);
+    if (!response.ok) {
+        const body = encodableSchema.safeParse(parsed);
+        throw new KitApiError({
+            ...(body.success && { body: body.data }),
+            retryAfter: response.headers.get("Retry-After") ?? undefined,
+            status: response.status,
+        });
+    }
+    return parsed;
+}
+/**
+ * Appends one documented query parameter.
+ *
+ * @param url Mutable request URL.
+ * @param parameter Query parameter metadata.
+ * @param value Public parameter value.
+ */
+function appendQuery(url, parameter, value) {
+    if (value == null)
+        return;
+    if (Array.isArray(value)) {
+        if (parameter.style === "form" && parameter.explode) {
+            for (const item of value) {
+                url.searchParams.append(parameter.providerName, stringifyQueryValue(item));
+            }
+        }
+        else {
+            url.searchParams.set(parameter.providerName, value.map(stringifyQueryValue).join(","));
+        }
+        return;
+    }
+    url.searchParams.set(parameter.providerName, stringifyQueryValue(value));
+}
+/**
+ * Converts a query value to its wire representation.
+ *
+ * @param value Public query value.
+ * @throws When the value is not scalar.
+ */
+function stringifyQueryValue(value) {
+    if (typeof value !== "boolean" &&
+        typeof value !== "number" &&
+        typeof value !== "string") {
+        throw new TypeError("Kit query parameters must be scalar.");
+    }
+    return String(value);
+}
+/**
+ * Validates a flattened action query value.
+ *
+ * @param value Public action field.
+ * @throws When the value is not a scalar or scalar array.
+ */
+function parseQueryValue(value) {
+    if (value === null ||
+        value === undefined ||
+        typeof value === "boolean" ||
+        typeof value === "number" ||
+        typeof value === "string") {
+        return value;
+    }
+    if (Array.isArray(value) &&
+        value.every((item) => typeof item === "boolean" ||
+            typeof item === "number" ||
+            typeof item === "string")) {
+        return value;
+    }
+    throw new TypeError("Kit query parameters must be scalar or scalar arrays.");
+}
+/**
+ * Encodes one required path parameter.
+ *
+ * @param value Public path value.
+ * @param name Public parameter name.
+ * @throws When the path value is missing or invalid.
+ */
+function encodePathSegment(value, name) {
+    if (typeof value !== "number" && typeof value !== "string") {
+        throw new TypeError(`Kit path parameter ${name} is required.`);
+    }
+    return encodeURIComponent(String(value));
+}
+/**
+ * Recursively maps Kit fields between public and wire names.
+ *
+ * @param value Value to transform.
+ * @param schema Provider wire schema.
+ * @param direction Mapping direction.
+ */
+function transformKitValue(value, schema, direction) {
+    const resolved = resolveWireSchema(schema);
+    if (Array.isArray(value)) {
+        const itemSchema = isRecord(resolved.items) ? resolved.items : {};
+        return value.map((item) => transformKitValue(item, itemSchema, direction));
+    }
+    if (!isRecord(value))
+        return value;
+    const properties = collectWireProperties(resolved);
+    return Object.fromEntries(Object.entries(value).map(([name, item]) => {
+        const providerName = direction === "toPublic"
+            ? name
+            : (Object.keys(properties).find((candidate) => camelCase(candidate) === name) ?? name);
+        const publicName = direction === "toPublic" && providerName in properties
+            ? camelCase(providerName)
+            : name;
+        const childSchemas = propertySchemas(resolved, providerName);
+        // Combine alternate provider shapes before recursively mapping nested keys.
+        const childSchema = childSchemas.length === 0
+            ? {}
+            : childSchemas.length === 1
+                ? (childSchemas[0] ?? {})
+                : { anyOf: childSchemas };
+        return [
+            direction === "toPublic" ? publicName : providerName,
+            transformKitValue(item, childSchema, direction),
+        ];
+    }));
+}
+/**
+ * Collects schema properties across composition branches.
+ *
+ * @param schema Provider wire schema.
+ */
+function collectWireProperties(schema) {
+    const resolved = resolveWireSchema(schema);
+    const properties = {};
+    return Object.assign(properties, isRecord(resolved.properties) ? resolved.properties : {}, ...schemaBranches(resolved).map(collectWireProperties));
+}
+/**
+ * Finds every schema declared for one provider field.
+ *
+ * @param schema Provider wire schema.
+ * @param providerName Provider field name.
+ */
+function propertySchemas(schema, providerName) {
+    const resolved = resolveWireSchema(schema);
+    // Inspect the direct declaration before recursively visiting composed branches.
+    const direct = isRecord(resolved.properties) && isRecord(resolved.properties[providerName])
+        ? [resolved.properties[providerName]]
+        : [];
+    return [
+        ...direct,
+        ...schemaBranches(resolved).flatMap((branch) => propertySchemas(branch, providerName)),
+    ];
+}
+/**
+ * Returns all composed schema branches.
+ *
+ * @param schema Provider wire schema.
+ */
+function schemaBranches(schema) {
+    return ["allOf", "anyOf", "oneOf"].flatMap((keyword) => Array.isArray(schema[keyword]) ? schema[keyword].filter(isRecord) : []);
+}
+/**
+ * Resolves a top-level provider component reference.
+ *
+ * @param schema Provider wire schema.
+ */
+function resolveWireSchema(schema) {
+    if (typeof schema.$ref !== "string")
+        return schema;
+    const name = /^#\/components\/schemas\/(.+)$/.exec(schema.$ref)?.[1];
+    return name ? (KIT_WIRE_DEFINITIONS[name] ?? schema) : schema;
+}
+/**
+ * Parses a provider response without assuming JSON on errors.
+ *
+ * @param response Provider response.
+ */
+async function parseResponse(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { response: text };
+    }
+}
+/**
+ * Extracts Kit's documented error messages.
+ *
+ * @param value Parsed provider response.
+ */
+function getErrorMessage(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (Array.isArray(value.errors)) {
+        const messages = value.errors.filter((item) => typeof item === "string" && item.length > 0);
+        if (messages.length > 0)
+            return messages.join("; ");
+    }
+    return typeof value.message === "string" && value.message
+        ? value.message
+        : undefined;
+}
+/**
+ * Converts one provider snake_case field name to camelCase.
+ *
+ * @param value Provider field name.
+ */
+function camelCase(value) {
+    return value.replace(/_([a-z\d])/g, (_match, letter) => letter.toUpperCase());
+}
+/**
+ * Narrows an unknown value to a record.
+ *
+ * @param value Candidate object.
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}