@automate.ax/integration-contracts 0.115.6 → 0.116.0

package/dist/millionverifier/api.d.ts

@@ -0,0 +1,62 @@
+import * as z from "zod";
+/** Structured failure returned by MillionVerifier. */
+export declare class MillionVerifierApiError extends Error {
+    /** Provider error classification or message. */
+    readonly code: string;
+    /** API path that failed. */
+    readonly path: string;
+    /** HTTP status returned by MillionVerifier. */
+    readonly status: number;
+    /**
+     * Creates a MillionVerifier provider error.
+     *
+     * @param options - Provider failure details.
+     * @param options.code - Provider error classification or message.
+     * @param options.path - API path that failed.
+     * @param options.status - HTTP status.
+     */
+    constructor(options: {
+        code: string;
+        path: string;
+        status: number;
+    });
+}
+/** Query values accepted by the MillionVerifier request helper. */
+export type MillionVerifierQueryValue = boolean | number | readonly (number | string)[] | string | undefined;
+/** Options accepted by the authenticated MillionVerifier request helper. */
+export interface MillionVerifierRequestOptions extends RequestInit {
+    /** Selects the real-time or bulk API origin and credential parameter. */
+    api: "bulk" | "single";
+    /** Query parameters appended to the request URL. */
+    query?: Record<string, MillionVerifierQueryValue>;
+}
+/**
+ * Creates an authenticated MillionVerifier HTTP client.
+ *
+ * @param secret - Resolved MillionVerifier integration secret.
+ */
+export declare function getMillionVerifierApi(secret: Record<string, unknown>): {
+    /**
+     * Sends an authenticated request to a MillionVerifier API.
+     *
+     * @param path - Absolute-path provider endpoint.
+     * @param options - API selection, native fetch options, and query values.
+     */
+    request(path: string, options: MillionVerifierRequestOptions): Promise<Response>;
+};
+/**
+ * Parses a JSON response and rejects MillionVerifier logical errors.
+ *
+ * The provider returns HTTP 200 for authentication, credit, file, and filter
+ * failures, so callers must inspect every JSON body.
+ *
+ * @param response - Successful transport response.
+ * @param path - API path used in a structured failure.
+ * @param schema - Expected success payload.
+ * @param options - Parsing exceptions for complete resource payloads.
+ * @param options.acceptErrorFieldWhenValid - Accepts a schema-valid resource
+ *   with provider error details.
+ */
+export declare function parseMillionVerifierJson<TSchema extends z.ZodType>(response: Response, path: string, schema: TSchema, options?: {
+    acceptErrorFieldWhenValid?: boolean;
+}): Promise<z.output<TSchema>>;

package/dist/millionverifier/api.js

@@ -0,0 +1,114 @@
+import * as z from "zod";
+const MILLIONVERIFIER_SECRET_SCHEMA = z.object({ apiKey: z.string().min(1) });
+const MILLIONVERIFIER_ERROR_SCHEMA = z.looseObject({
+    error: z.string().optional(),
+    result: z.string().optional(),
+});
+/** Structured failure returned by MillionVerifier. */
+export class MillionVerifierApiError extends Error {
+    /** Provider error classification or message. */
+    code;
+    /** API path that failed. */
+    path;
+    /** HTTP status returned by MillionVerifier. */
+    status;
+    /**
+     * Creates a MillionVerifier provider error.
+     *
+     * @param options - Provider failure details.
+     * @param options.code - Provider error classification or message.
+     * @param options.path - API path that failed.
+     * @param options.status - HTTP status.
+     */
+    constructor(options) {
+        super(`MillionVerifier ${options.path} failed: ${options.code}`);
+        this.name = "MillionVerifierApiError";
+        this.code = options.code;
+        this.path = options.path;
+        this.status = options.status;
+    }
+}
+/**
+ * Creates an authenticated MillionVerifier HTTP client.
+ *
+ * @param secret - Resolved MillionVerifier integration secret.
+ */
+export function getMillionVerifierApi(secret) {
+    const { apiKey } = MILLIONVERIFIER_SECRET_SCHEMA.parse(secret);
+    return {
+        /**
+         * Sends an authenticated request to a MillionVerifier API.
+         *
+         * @param path - Absolute-path provider endpoint.
+         * @param options - API selection, native fetch options, and query values.
+         */
+        async request(path, options) {
+            const { api, query, ...requestInit } = options;
+            const url = new URL(path, api === "single"
+                ? "https://api.millionverifier.com"
+                : "https://bulkapi.millionverifier.com");
+            url.searchParams.set(api === "single" ? "api" : "key", apiKey);
+            for (const [key, value] of Object.entries(query ?? {})) {
+                if (value === undefined)
+                    continue;
+                url.searchParams.set(key, Array.isArray(value) ? value.join(",") : String(value));
+            }
+            const response = await fetch(url, requestInit);
+            if (!response.ok) {
+                throw new MillionVerifierApiError({
+                    code: await providerError(response),
+                    path,
+                    status: response.status,
+                });
+            }
+            return response;
+        },
+    };
+}
+/**
+ * Parses a JSON response and rejects MillionVerifier logical errors.
+ *
+ * The provider returns HTTP 200 for authentication, credit, file, and filter
+ * failures, so callers must inspect every JSON body.
+ *
+ * @param response - Successful transport response.
+ * @param path - API path used in a structured failure.
+ * @param schema - Expected success payload.
+ * @param options - Parsing exceptions for complete resource payloads.
+ * @param options.acceptErrorFieldWhenValid - Accepts a schema-valid resource
+ *   with provider error details.
+ */
+export async function parseMillionVerifierJson(response, path, schema, options) {
+    const value = await response.json();
+    if (options?.acceptErrorFieldWhenValid) {
+        const result = schema.safeParse(value);
+        if (result.success)
+            return result.data;
+    }
+    const failure = MILLIONVERIFIER_ERROR_SCHEMA.safeParse(value);
+    if (failure.success &&
+        failure.data.error &&
+        failure.data.error.trim().length > 0) {
+        throw new MillionVerifierApiError({
+            code: failure.data.error,
+            path,
+            status: response.status,
+        });
+    }
+    return schema.parse(value);
+}
+/**
+ * Extracts the most useful provider error from an unsuccessful response.
+ *
+ * @param response - Provider response to inspect.
+ */
+async function providerError(response) {
+    const text = await response.text();
+    try {
+        const failure = MILLIONVERIFIER_ERROR_SCHEMA.parse(JSON.parse(text));
+        return failure.error || failure.result || `HTTP ${response.status}`;
+    }
+    catch {
+        return text.trim() || `HTTP ${response.status}`;
+    }
+}

package/dist/millionverifier/events.d.ts

@@ -0,0 +1,126 @@
+import * as z from "zod";
+export declare const MILLIONVERIFIER_NO_CREDIT_EVENT_SCHEMA: z.ZodObject<{
+    reason: z.ZodLiteral<"noCredit">;
+}, z.core.$strip>;
+export declare const MILLIONVERIFIER_LOW_CREDIT_EVENT_SCHEMA: z.ZodObject<{
+    credits: z.ZodNumber;
+    reason: z.ZodLiteral<"lowCredit">;
+}, z.core.$strip>;
+export declare const MILLIONVERIFIER_FILE_READY_EVENT_SCHEMA: z.ZodObject<{
+    file: z.ZodObject<{
+        catchAll: z.ZodNumber;
+        disposable: z.ZodNumber;
+        fileId: z.ZodString;
+        fileName: z.ZodString;
+        invalid: z.ZodNumber;
+        ok: z.ZodNumber;
+        totalRows: z.ZodNumber;
+        uniqueEmails: z.ZodNumber;
+        unknown: z.ZodNumber;
+    }, z.core.$strip>;
+    reason: z.ZodLiteral<"fileReady">;
+}, z.core.$strip>;
+export declare const MILLIONVERIFIER_FILE_DELETION_SCHEDULED_EVENT_SCHEMA: z.ZodObject<{
+    file: z.ZodObject<{
+        deletesIn: z.ZodString;
+        fileId: z.ZodString;
+        fileName: z.ZodString;
+    }, z.core.$strip>;
+    reason: z.ZodLiteral<"fileDeletionScheduled">;
+}, z.core.$strip>;
+export declare const MILLIONVERIFIER_EVENT_SCHEMA: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    reason: z.ZodLiteral<"noCredit">;
+}, z.core.$strip>, z.ZodObject<{
+    credits: z.ZodNumber;
+    reason: z.ZodLiteral<"lowCredit">;
+}, z.core.$strip>, z.ZodObject<{
+    file: z.ZodObject<{
+        catchAll: z.ZodNumber;
+        disposable: z.ZodNumber;
+        fileId: z.ZodString;
+        fileName: z.ZodString;
+        invalid: z.ZodNumber;
+        ok: z.ZodNumber;
+        totalRows: z.ZodNumber;
+        uniqueEmails: z.ZodNumber;
+        unknown: z.ZodNumber;
+    }, z.core.$strip>;
+    reason: z.ZodLiteral<"fileReady">;
+}, z.core.$strip>, z.ZodObject<{
+    file: z.ZodObject<{
+        deletesIn: z.ZodString;
+        fileId: z.ZodString;
+        fileName: z.ZodString;
+    }, z.core.$strip>;
+    reason: z.ZodLiteral<"fileDeletionScheduled">;
+}, z.core.$strip>], "reason">;
+export declare const MILLIONVERIFIER_WEBHOOK_WIRE_SCHEMA: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    reason: z.ZodLiteral<"no_credit">;
+}, z.core.$loose>, z.ZodObject<{
+    credits: z.ZodNumber;
+    reason: z.ZodLiteral<"low_credit">;
+}, z.core.$loose>, z.ZodObject<{
+    file: z.ZodObject<{
+        catch_all: z.ZodNumber;
+        disposable: z.ZodNumber;
+        file_id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+        file_name: z.ZodString;
+        invalid: z.ZodNumber;
+        ok: z.ZodNumber;
+        total_rows: z.ZodNumber;
+        unique_emails: z.ZodNumber;
+        unknown: z.ZodNumber;
+    }, z.core.$loose>;
+    reason: z.ZodLiteral<"file_ready">;
+}, z.core.$loose>, z.ZodObject<{
+    file: z.ZodObject<{
+        file_delete: z.ZodString;
+        file_id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+        file_name: z.ZodString;
+    }, z.core.$loose>;
+    reason: z.ZodLiteral<"file_delete">;
+}, z.core.$loose>], "reason">;
+/**
+ * Normalizes one documented MillionVerifier notification payload.
+ *
+ * @param value - Untrusted provider callback payload.
+ */
+export declare function normalizeMillionVerifierEvent(value: unknown): {
+    reason: "noCredit";
+    credits?: undefined;
+    file?: undefined;
+} | {
+    credits: number;
+    reason: "lowCredit";
+    file?: undefined;
+} | {
+    file: {
+        deletesIn: string;
+        fileId: string;
+        fileName: string;
+        catchAll?: undefined;
+        disposable?: undefined;
+        invalid?: undefined;
+        ok?: undefined;
+        totalRows?: undefined;
+        uniqueEmails?: undefined;
+        unknown?: undefined;
+    };
+    reason: "fileDeletionScheduled";
+    credits?: undefined;
+} | {
+    file: {
+        catchAll: number;
+        disposable: number;
+        fileId: string;
+        fileName: string;
+        invalid: number;
+        ok: number;
+        totalRows: number;
+        uniqueEmails: number;
+        unknown: number;
+        deletesIn?: undefined;
+    };
+    reason: "fileReady";
+    credits?: undefined;
+};

package/dist/millionverifier/events.js

@@ -0,0 +1,103 @@
+import * as z from "zod";
+const FILE_ID_WIRE_SCHEMA = z.union([z.string(), z.number()]).transform(String);
+export const MILLIONVERIFIER_NO_CREDIT_EVENT_SCHEMA = z.object({
+    reason: z.literal("noCredit"),
+});
+export const MILLIONVERIFIER_LOW_CREDIT_EVENT_SCHEMA = z.object({
+    credits: z.number().int().nonnegative(),
+    reason: z.literal("lowCredit"),
+});
+export const MILLIONVERIFIER_FILE_READY_EVENT_SCHEMA = z.object({
+    file: z.object({
+        catchAll: z.number().int().nonnegative(),
+        disposable: z.number().int().nonnegative(),
+        fileId: z.string(),
+        fileName: z.string(),
+        invalid: z.number().int().nonnegative(),
+        ok: z.number().int().nonnegative(),
+        totalRows: z.number().int().nonnegative(),
+        uniqueEmails: z.number().int().nonnegative(),
+        unknown: z.number().int().nonnegative(),
+    }),
+    reason: z.literal("fileReady"),
+});
+export const MILLIONVERIFIER_FILE_DELETION_SCHEDULED_EVENT_SCHEMA = z.object({
+    file: z.object({
+        deletesIn: z.string().min(1),
+        fileId: z.string(),
+        fileName: z.string(),
+    }),
+    reason: z.literal("fileDeletionScheduled"),
+});
+export const MILLIONVERIFIER_EVENT_SCHEMA = z.discriminatedUnion("reason", [
+    MILLIONVERIFIER_NO_CREDIT_EVENT_SCHEMA,
+    MILLIONVERIFIER_LOW_CREDIT_EVENT_SCHEMA,
+    MILLIONVERIFIER_FILE_READY_EVENT_SCHEMA,
+    MILLIONVERIFIER_FILE_DELETION_SCHEDULED_EVENT_SCHEMA,
+]);
+export const MILLIONVERIFIER_WEBHOOK_WIRE_SCHEMA = z.discriminatedUnion("reason", [
+    z.looseObject({ reason: z.literal("no_credit") }),
+    z.looseObject({
+        credits: z.number().int().nonnegative(),
+        reason: z.literal("low_credit"),
+    }),
+    z.looseObject({
+        file: z.looseObject({
+            catch_all: z.number().int().nonnegative(),
+            disposable: z.number().int().nonnegative(),
+            file_id: FILE_ID_WIRE_SCHEMA,
+            file_name: z.string(),
+            invalid: z.number().int().nonnegative(),
+            ok: z.number().int().nonnegative(),
+            total_rows: z.number().int().nonnegative(),
+            unique_emails: z.number().int().nonnegative(),
+            unknown: z.number().int().nonnegative(),
+        }),
+        reason: z.literal("file_ready"),
+    }),
+    z.looseObject({
+        file: z.looseObject({
+            file_delete: z.string().min(1),
+            file_id: FILE_ID_WIRE_SCHEMA,
+            file_name: z.string(),
+        }),
+        reason: z.literal("file_delete"),
+    }),
+]);
+/**
+ * Normalizes one documented MillionVerifier notification payload.
+ *
+ * @param value - Untrusted provider callback payload.
+ */
+export function normalizeMillionVerifierEvent(value) {
+    const event = MILLIONVERIFIER_WEBHOOK_WIRE_SCHEMA.parse(value);
+    if (event.reason === "no_credit")
+        return { reason: "noCredit" };
+    if (event.reason === "low_credit") {
+        return { credits: event.credits, reason: "lowCredit" };
+    }
+    if (event.reason === "file_delete") {
+        return {
+            file: {
+                deletesIn: event.file.file_delete,
+                fileId: event.file.file_id,
+                fileName: event.file.file_name,
+            },
+            reason: "fileDeletionScheduled",
+        };
+    }
+    return {
+        file: {
+            catchAll: event.file.catch_all,
+            disposable: event.file.disposable,
+            fileId: event.file.file_id,
+            fileName: event.file.file_name,
+            invalid: event.file.invalid,
+            ok: event.file.ok,
+            totalRows: event.file.total_rows,
+            uniqueEmails: event.file.unique_emails,
+            unknown: event.file.unknown,
+        },
+        reason: "fileReady",
+    };
+}

package/dist/millionverifier/index.d.ts

@@ -0,0 +1,77 @@
+export * from "./api.js";
+export * from "./events.js";
+export * from "./schemas.js";
+import * as z from "zod";
+export declare const MILLIONVERIFIER_TRIGGER_CONFIG_SCHEMA: z.ZodObject<{}, z.core.$strip>;
+export declare const millionVerifierTriggerContracts: {
+    readonly "millionverifier.event": {
+        configSchema: z.ZodObject<{}, z.core.$strip>;
+        eventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            reason: z.ZodLiteral<"noCredit">;
+        }, z.core.$strip>, z.ZodObject<{
+            credits: z.ZodNumber;
+            reason: z.ZodLiteral<"lowCredit">;
+        }, z.core.$strip>, z.ZodObject<{
+            file: z.ZodObject<{
+                catchAll: z.ZodNumber;
+                disposable: z.ZodNumber;
+                fileId: z.ZodString;
+                fileName: z.ZodString;
+                invalid: z.ZodNumber;
+                ok: z.ZodNumber;
+                totalRows: z.ZodNumber;
+                uniqueEmails: z.ZodNumber;
+                unknown: z.ZodNumber;
+            }, z.core.$strip>;
+            reason: z.ZodLiteral<"fileReady">;
+        }, z.core.$strip>, z.ZodObject<{
+            file: z.ZodObject<{
+                deletesIn: z.ZodString;
+                fileId: z.ZodString;
+                fileName: z.ZodString;
+            }, z.core.$strip>;
+            reason: z.ZodLiteral<"fileDeletionScheduled">;
+        }, z.core.$strip>], "reason">;
+    };
+    readonly "millionverifier.noCredit": {
+        configSchema: z.ZodObject<{}, z.core.$strip>;
+        eventSchema: z.ZodObject<{
+            reason: z.ZodLiteral<"noCredit">;
+        }, z.core.$strip>;
+    };
+    readonly "millionverifier.lowCredit": {
+        configSchema: z.ZodObject<{}, z.core.$strip>;
+        eventSchema: z.ZodObject<{
+            credits: z.ZodNumber;
+            reason: z.ZodLiteral<"lowCredit">;
+        }, z.core.$strip>;
+    };
+    readonly "millionverifier.fileReady": {
+        configSchema: z.ZodObject<{}, z.core.$strip>;
+        eventSchema: z.ZodObject<{
+            file: z.ZodObject<{
+                catchAll: z.ZodNumber;
+                disposable: z.ZodNumber;
+                fileId: z.ZodString;
+                fileName: z.ZodString;
+                invalid: z.ZodNumber;
+                ok: z.ZodNumber;
+                totalRows: z.ZodNumber;
+                uniqueEmails: z.ZodNumber;
+                unknown: z.ZodNumber;
+            }, z.core.$strip>;
+            reason: z.ZodLiteral<"fileReady">;
+        }, z.core.$strip>;
+    };
+    readonly "millionverifier.fileDeletionScheduled": {
+        configSchema: z.ZodObject<{}, z.core.$strip>;
+        eventSchema: z.ZodObject<{
+            file: z.ZodObject<{
+                deletesIn: z.ZodString;
+                fileId: z.ZodString;
+                fileName: z.ZodString;
+            }, z.core.$strip>;
+            reason: z.ZodLiteral<"fileDeletionScheduled">;
+        }, z.core.$strip>;
+    };
+};

package/dist/millionverifier/index.js

@@ -0,0 +1,17 @@
+export * from "./api.js";
+export * from "./events.js";
+export * from "./schemas.js";
+import * as z from "zod";
+import { MILLIONVERIFIER_EVENT_SCHEMA, MILLIONVERIFIER_FILE_DELETION_SCHEDULED_EVENT_SCHEMA, MILLIONVERIFIER_FILE_READY_EVENT_SCHEMA, MILLIONVERIFIER_LOW_CREDIT_EVENT_SCHEMA, MILLIONVERIFIER_NO_CREDIT_EVENT_SCHEMA, } from "./events.js";
+export const MILLIONVERIFIER_TRIGGER_CONFIG_SCHEMA = z.object({});
+const contract = (eventSchema) => ({
+    configSchema: MILLIONVERIFIER_TRIGGER_CONFIG_SCHEMA,
+    eventSchema,
+});
+export const millionVerifierTriggerContracts = {
+    "millionverifier.event": contract(MILLIONVERIFIER_EVENT_SCHEMA),
+    "millionverifier.noCredit": contract(MILLIONVERIFIER_NO_CREDIT_EVENT_SCHEMA),
+    "millionverifier.lowCredit": contract(MILLIONVERIFIER_LOW_CREDIT_EVENT_SCHEMA),
+    "millionverifier.fileReady": contract(MILLIONVERIFIER_FILE_READY_EVENT_SCHEMA),
+    "millionverifier.fileDeletionScheduled": contract(MILLIONVERIFIER_FILE_DELETION_SCHEDULED_EVENT_SCHEMA),
+};