@automate.ax/integration-contracts 0.115.6 → 0.116.0

package/dist/millionverifier/schemas.d.ts

@@ -0,0 +1,226 @@
+import * as z from "zod";
+export declare const MILLIONVERIFIER_FILE_ID_SCHEMA: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+export declare const MILLIONVERIFIER_FILE_STATUS_SCHEMA: z.ZodEnum<{
+    error: "error";
+    paused: "paused";
+    canceled: "canceled";
+    finished: "finished";
+    inProgress: "inProgress";
+    inQueueToStart: "inQueueToStart";
+}>;
+export declare const MILLIONVERIFIER_FILE_SCHEMA: z.ZodObject<{
+    catchAll: z.ZodNumber;
+    createdAt: z.ZodString;
+    creditsRequired: z.ZodNumber;
+    disposable: z.ZodNumber;
+    error: z.ZodString;
+    estimatedTimeSeconds: z.ZodNumber;
+    fileId: z.ZodString;
+    fileName: z.ZodString;
+    invalid: z.ZodNumber;
+    ok: z.ZodNumber;
+    percent: z.ZodNumber;
+    reverify: z.ZodNumber;
+    status: z.ZodEnum<{
+        error: "error";
+        paused: "paused";
+        canceled: "canceled";
+        finished: "finished";
+        inProgress: "inProgress";
+        inQueueToStart: "inQueueToStart";
+    }>;
+    totalRows: z.ZodNumber;
+    uniqueEmails: z.ZodNumber;
+    unknown: z.ZodNumber;
+    unverified: z.ZodNumber;
+    updatedAt: z.ZodString;
+    verified: z.ZodNumber;
+}, z.core.$strip>;
+export declare const MILLIONVERIFIER_EMAIL_RESULT_SCHEMA: z.ZodEnum<{
+    unknown: "unknown";
+    error: "error";
+    invalid: "invalid";
+    ok: "ok";
+    catchAll: "catchAll";
+    disposable: "disposable";
+    unverified: "unverified";
+}>;
+export declare const MILLIONVERIFIER_EMAIL_VERIFICATION_SCHEMA: z.ZodObject<{
+    credits: z.ZodNumber;
+    didYouMean: z.ZodString;
+    email: z.ZodString;
+    error: z.ZodString;
+    executionTimeMilliseconds: z.ZodNumber;
+    free: z.ZodBoolean;
+    liveMode: z.ZodBoolean;
+    quality: z.ZodOptional<z.ZodEnum<{
+        good: "good";
+        bad: "bad";
+        risky: "risky";
+    }>>;
+    result: z.ZodEnum<{
+        unknown: "unknown";
+        error: "error";
+        invalid: "invalid";
+        ok: "ok";
+        catchAll: "catchAll";
+        disposable: "disposable";
+        unverified: "unverified";
+    }>;
+    resultCode: z.ZodNumber;
+    role: z.ZodBoolean;
+    subresult: z.ZodString;
+}, z.core.$strip>;
+export declare const MILLIONVERIFIER_CREDITS_SCHEMA: z.ZodObject<{
+    bulkCredits: z.ZodNumber;
+    credits: z.ZodNumber;
+    plan: z.ZodNumber;
+    renewingCredits: z.ZodNumber;
+}, z.core.$strip>;
+export declare const MILLIONVERIFIER_FILE_WIRE_SCHEMA: z.ZodPipe<z.ZodObject<{
+    catch_all: z.ZodNumber;
+    createdate: z.ZodString;
+    credit: z.ZodNumber;
+    disposable: z.ZodNumber;
+    error: z.ZodString;
+    estimated_time_sec: 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;
+    percent: z.ZodNumber;
+    reverify: z.ZodNumber;
+    status: z.ZodEnum<{
+        error: "error";
+        in_progress: "in_progress";
+        paused: "paused";
+        canceled: "canceled";
+        finished: "finished";
+        in_queue_to_start: "in_queue_to_start";
+    }>;
+    total_rows: z.ZodNumber;
+    unique_emails: z.ZodNumber;
+    unknown: z.ZodNumber;
+    unverified: z.ZodNumber;
+    updated_at: z.ZodString;
+    verified: z.ZodNumber;
+}, z.core.$loose>, z.ZodTransform<{
+    catchAll: number;
+    createdAt: string;
+    creditsRequired: number;
+    disposable: number;
+    error: string;
+    estimatedTimeSeconds: number;
+    fileId: string;
+    fileName: string;
+    invalid: number;
+    ok: number;
+    percent: number;
+    reverify: number;
+    status: "error" | "paused" | "canceled" | "finished" | "inProgress" | "inQueueToStart";
+    totalRows: number;
+    uniqueEmails: number;
+    unknown: number;
+    unverified: number;
+    updatedAt: string;
+    verified: number;
+}, {
+    [x: string]: unknown;
+    catch_all: number;
+    createdate: string;
+    credit: number;
+    disposable: number;
+    error: string;
+    estimated_time_sec: number;
+    file_id: string;
+    file_name: string;
+    invalid: number;
+    ok: number;
+    percent: number;
+    reverify: number;
+    status: "error" | "in_progress" | "paused" | "canceled" | "finished" | "in_queue_to_start";
+    total_rows: number;
+    unique_emails: number;
+    unknown: number;
+    unverified: number;
+    updated_at: string;
+    verified: number;
+}>>;
+export declare const MILLIONVERIFIER_EMAIL_VERIFICATION_WIRE_SCHEMA: z.ZodPipe<z.ZodObject<{
+    credits: z.ZodNumber;
+    didyoumean: z.ZodString;
+    email: z.ZodString;
+    error: z.ZodString;
+    executiontime: z.ZodNumber;
+    free: z.ZodBoolean;
+    livemode: z.ZodBoolean;
+    quality: z.ZodOptional<z.ZodEnum<{
+        "": "";
+        good: "good";
+        bad: "bad";
+        risky: "risky";
+    }>>;
+    result: z.ZodEnum<{
+        "": "";
+        unknown: "unknown";
+        error: "error";
+        invalid: "invalid";
+        ok: "ok";
+        disposable: "disposable";
+        catch_all: "catch_all";
+        unverified: "unverified";
+    }>;
+    resultcode: z.ZodNumber;
+    role: z.ZodBoolean;
+    subresult: z.ZodString;
+}, z.core.$loose>, z.ZodTransform<{
+    credits: number;
+    didYouMean: string;
+    email: string;
+    error: string;
+    executionTimeMilliseconds: number;
+    free: boolean;
+    liveMode: boolean;
+    result: "unknown" | "error" | "invalid" | "ok" | "catchAll" | "disposable" | "unverified";
+    resultCode: number;
+    role: boolean;
+    subresult: string;
+    quality?: "good" | "bad" | "risky" | undefined;
+}, {
+    [x: string]: unknown;
+    credits: number;
+    didyoumean: string;
+    email: string;
+    error: string;
+    executiontime: number;
+    free: boolean;
+    livemode: boolean;
+    result: "" | "unknown" | "error" | "invalid" | "ok" | "disposable" | "catch_all" | "unverified";
+    resultcode: number;
+    role: boolean;
+    subresult: string;
+    quality?: "" | "good" | "bad" | "risky" | undefined;
+}>>;
+export declare const MILLIONVERIFIER_CREDITS_WIRE_SCHEMA: z.ZodPipe<z.ZodObject<{
+    bulk_credits: z.ZodNumber;
+    credits: z.ZodNumber;
+    plan: z.ZodNumber;
+    renewing_credits: z.ZodNumber;
+}, z.core.$loose>, z.ZodTransform<{
+    bulkCredits: number;
+    credits: number;
+    plan: number;
+    renewingCredits: number;
+}, {
+    [x: string]: unknown;
+    bulk_credits: number;
+    credits: number;
+    plan: number;
+    renewing_credits: number;
+}>>;
+/**
+ * Maps a public file status to MillionVerifier's query value.
+ *
+ * @param status - Public file status.
+ */
+export declare function toMillionVerifierFileStatus(status: z.output<typeof MILLIONVERIFIER_FILE_STATUS_SCHEMA>): "error" | "in_progress" | "paused" | "canceled" | "finished" | "in_queue_to_start";

package/dist/millionverifier/schemas.js

@@ -0,0 +1,188 @@
+import * as z from "zod";
+export const MILLIONVERIFIER_FILE_ID_SCHEMA = z
+    .union([z.string().regex(/^\d+$/), z.number().int().positive()])
+    .transform(String);
+export const MILLIONVERIFIER_FILE_STATUS_SCHEMA = z.enum([
+    "inProgress",
+    "error",
+    "finished",
+    "canceled",
+    "paused",
+    "inQueueToStart",
+]);
+export const MILLIONVERIFIER_FILE_SCHEMA = z.object({
+    catchAll: z.number().int().nonnegative(),
+    createdAt: z.string(),
+    creditsRequired: z.number().int().nonnegative(),
+    disposable: z.number().int().nonnegative(),
+    error: z.string(),
+    estimatedTimeSeconds: z.number().int().nonnegative(),
+    fileId: z.string(),
+    fileName: z.string(),
+    invalid: z.number().int().nonnegative(),
+    ok: z.number().int().nonnegative(),
+    percent: z.number().int().min(0).max(100),
+    reverify: z.number().int().nonnegative(),
+    status: MILLIONVERIFIER_FILE_STATUS_SCHEMA,
+    totalRows: z.number().int().nonnegative(),
+    uniqueEmails: z.number().int().nonnegative(),
+    unknown: z.number().int().nonnegative(),
+    unverified: z.number().int().nonnegative(),
+    updatedAt: z.string(),
+    verified: z.number().int().nonnegative(),
+});
+export const MILLIONVERIFIER_EMAIL_RESULT_SCHEMA = z.enum([
+    "unverified",
+    "ok",
+    "catchAll",
+    "unknown",
+    "error",
+    "disposable",
+    "invalid",
+]);
+export const MILLIONVERIFIER_EMAIL_VERIFICATION_SCHEMA = z.object({
+    credits: z.number().int().nonnegative(),
+    didYouMean: z.string(),
+    email: z.string(),
+    error: z.string(),
+    executionTimeMilliseconds: z.number().int().nonnegative(),
+    free: z.boolean(),
+    liveMode: z.boolean(),
+    quality: z.enum(["good", "bad", "risky"]).optional(),
+    result: MILLIONVERIFIER_EMAIL_RESULT_SCHEMA,
+    resultCode: z.number().int().min(0).max(6),
+    role: z.boolean(),
+    subresult: z.string(),
+});
+export const MILLIONVERIFIER_CREDITS_SCHEMA = z.object({
+    bulkCredits: z.number().int().nonnegative(),
+    credits: z.number().int().nonnegative(),
+    plan: z.number().int(),
+    renewingCredits: z.number().int().nonnegative(),
+});
+const PROVIDER_FILE_STATUS_SCHEMA = z.enum([
+    "in_progress",
+    "error",
+    "finished",
+    "canceled",
+    "paused",
+    "in_queue_to_start",
+]);
+export const MILLIONVERIFIER_FILE_WIRE_SCHEMA = z
+    .looseObject({
+    catch_all: z.number().int().nonnegative(),
+    createdate: z.string(),
+    credit: z.number().int().nonnegative(),
+    disposable: z.number().int().nonnegative(),
+    error: z.string(),
+    estimated_time_sec: z.number().int().nonnegative(),
+    file_id: z.union([z.string(), z.number()]).transform(String),
+    file_name: z.string(),
+    invalid: z.number().int().nonnegative(),
+    ok: z.number().int().nonnegative(),
+    percent: z.number().int().min(0).max(100),
+    reverify: z.number().int().nonnegative(),
+    status: PROVIDER_FILE_STATUS_SCHEMA,
+    total_rows: z.number().int().nonnegative(),
+    unique_emails: z.number().int().nonnegative(),
+    unknown: z.number().int().nonnegative(),
+    unverified: z.number().int().nonnegative(),
+    updated_at: z.string(),
+    verified: z.number().int().nonnegative(),
+})
+    .transform((file) => MILLIONVERIFIER_FILE_SCHEMA.parse({
+    catchAll: file.catch_all,
+    createdAt: file.createdate,
+    creditsRequired: file.credit,
+    disposable: file.disposable,
+    error: file.error,
+    estimatedTimeSeconds: file.estimated_time_sec,
+    fileId: file.file_id,
+    fileName: file.file_name,
+    invalid: file.invalid,
+    ok: file.ok,
+    percent: file.percent,
+    reverify: file.reverify,
+    status: fromProviderFileStatus(file.status),
+    totalRows: file.total_rows,
+    uniqueEmails: file.unique_emails,
+    unknown: file.unknown,
+    unverified: file.unverified,
+    updatedAt: file.updated_at,
+    verified: file.verified,
+}));
+export const MILLIONVERIFIER_EMAIL_VERIFICATION_WIRE_SCHEMA = z
+    .looseObject({
+    credits: z.number().int().nonnegative(),
+    didyoumean: z.string(),
+    email: z.string(),
+    error: z.string(),
+    executiontime: z.number().int().nonnegative(),
+    free: z.boolean(),
+    livemode: z.boolean(),
+    quality: z.enum(["", "good", "bad", "risky"]).optional(),
+    result: z.enum([
+        "",
+        "unverified",
+        "ok",
+        "catch_all",
+        "unknown",
+        "error",
+        "disposable",
+        "invalid",
+    ]),
+    resultcode: z.number().int().min(0).max(6),
+    role: z.boolean(),
+    subresult: z.string(),
+})
+    .transform((result) => MILLIONVERIFIER_EMAIL_VERIFICATION_SCHEMA.parse({
+    credits: result.credits,
+    didYouMean: result.didyoumean,
+    email: result.email,
+    error: result.error,
+    executionTimeMilliseconds: result.executiontime,
+    free: result.free,
+    liveMode: result.livemode,
+    quality: result.quality || undefined,
+    result: result.result === "catch_all" ? "catchAll" : result.result || "error",
+    resultCode: result.resultcode,
+    role: result.role,
+    subresult: result.subresult,
+}));
+export const MILLIONVERIFIER_CREDITS_WIRE_SCHEMA = z
+    .looseObject({
+    bulk_credits: z.number().int().nonnegative(),
+    credits: z.number().int().nonnegative(),
+    plan: z.number().int(),
+    renewing_credits: z.number().int().nonnegative(),
+})
+    .transform((credits) => MILLIONVERIFIER_CREDITS_SCHEMA.parse({
+    bulkCredits: credits.bulk_credits,
+    credits: credits.credits,
+    plan: credits.plan,
+    renewingCredits: credits.renewing_credits,
+}));
+/**
+ * Maps a provider file status to the public camelCase discriminator.
+ *
+ * @param status - Provider file status.
+ */
+function fromProviderFileStatus(status) {
+    if (status === "in_progress")
+        return "inProgress";
+    if (status === "in_queue_to_start")
+        return "inQueueToStart";
+    return status;
+}
+/**
+ * Maps a public file status to MillionVerifier's query value.
+ *
+ * @param status - Public file status.
+ */
+export function toMillionVerifierFileStatus(status) {
+    if (status === "inProgress")
+        return "in_progress";
+    if (status === "inQueueToStart")
+        return "in_queue_to_start";
+    return status;
+}

package/dist/triggers.d.ts

@@ -12,6 +12,7 @@ import type { googleFormsTriggerContracts } from "./google-forms/index.js";
 import type { googleMeetTriggerContracts } from "./google-meet/index.js";
 import type { googleSheetsTriggerContracts } from "./google-sheets/index.js";
 import type { linearTriggerContracts } from "./linear/index.js";
+import type { millionVerifierTriggerContracts } from "./millionverifier/index.js";
 import type { notionTriggerContracts } from "./notion/index.js";
 import type { outlookTriggerContracts } from "./outlook/index.js";
 import type { resendTriggerContracts } from "./resend/index.js";
@@ -23,7 +24,7 @@ import type { vercelTriggerContracts } from "./vercel/index.js";
 import type { webflowTriggerContracts } from "./webflow/index.js";
 import type { whatsappTriggerContracts } from "./whatsapp/index.js";
 import type { z } from "zod";
-export type TriggerContractMap = typeof airtableTriggerContracts & typeof automateTriggerContracts & typeof asanaTriggerContracts & typeof brevoTriggerContracts & typeof convexTriggerContracts & typeof closeTriggerContracts & typeof cloudflareTriggerContracts & typeof githubTriggerContracts & typeof gmailTriggerContracts & typeof googleCalendarTriggerContracts & typeof googleFormsTriggerContracts & typeof googleMeetTriggerContracts & typeof googleSheetsTriggerContracts & typeof linearTriggerContracts & typeof notionTriggerContracts & typeof outlookTriggerContracts & typeof resendTriggerContracts & typeof slackTriggerContracts & typeof stripeTriggerContracts & typeof teamsTriggerContracts & typeof trelloTriggerContracts & typeof vercelTriggerContracts & typeof webflowTriggerContracts & typeof whatsappTriggerContracts;
+export type TriggerContractMap = typeof airtableTriggerContracts & typeof automateTriggerContracts & typeof asanaTriggerContracts & typeof brevoTriggerContracts & typeof convexTriggerContracts & typeof closeTriggerContracts & typeof cloudflareTriggerContracts & typeof githubTriggerContracts & typeof gmailTriggerContracts & typeof googleCalendarTriggerContracts & typeof googleFormsTriggerContracts & typeof googleMeetTriggerContracts & typeof googleSheetsTriggerContracts & typeof linearTriggerContracts & typeof millionVerifierTriggerContracts & typeof notionTriggerContracts & typeof outlookTriggerContracts & typeof resendTriggerContracts & typeof slackTriggerContracts & typeof stripeTriggerContracts & typeof teamsTriggerContracts & typeof trelloTriggerContracts & typeof vercelTriggerContracts & typeof webflowTriggerContracts & typeof whatsappTriggerContracts;
 export type IntegrationTriggerType = keyof TriggerContractMap;
 /** Canonical authoring configuration for one integration trigger type. */
 export type TriggerConfig<TType extends IntegrationTriggerType> = z.input<TriggerContractMap[TType]["configSchema"]> extends Record<string, never> ? object : z.input<TriggerContractMap[TType]["configSchema"]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automate.ax/integration-contracts",
-  "version": "0.115.6",
+  "version": "0.116.0",
   "description": "Shared integration payload contracts and provider primitives for Automate.ax.",
   "license": "MIT",
   "repository": {
@@ -33,6 +33,7 @@
       "./github": "./src/github/index.ts",
       "./jobnimbus": "./src/jobnimbus/index.ts",
       "./linear": "./src/linear/index.ts",
+      "./millionverifier": "./src/millionverifier/index.ts",
       "./notion": "./src/notion/index.ts",
       "./outlook": "./src/outlook/index.ts",
       "./resend": "./src/resend/index.ts",
@@ -51,7 +52,7 @@
     }
   },
   "dependencies": {
-    "@automate.ax/codec": "0.115.6",
+    "@automate.ax/codec": "0.116.0",
     "@cfworker/json-schema": "^4.1.1",
     "@googleapis/calendar": "^15.0.0",
     "@googleapis/forms": "^6.0.1",
@@ -177,6 +178,11 @@
       "types": "./dist/linear/index.d.ts",
       "default": "./dist/linear/index.js"
     },
+    "./millionverifier": {
+      "bun": "./src/millionverifier/index.ts",
+      "types": "./dist/millionverifier/index.d.ts",
+      "default": "./dist/millionverifier/index.js"
+    },
     "./notion": {
       "bun": "./src/notion/index.ts",
       "types": "./dist/notion/index.d.ts",

package/src/millionverifier/api.ts

@@ -0,0 +1,151 @@
+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. */
+  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 }) {
+    super(`MillionVerifier ${options.path} failed: ${options.code}`)
+    this.name = "MillionVerifierApiError"
+    this.code = options.code
+    this.path = options.path
+    this.status = options.status
+  }
+}
+
+/** 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 function getMillionVerifierApi(secret: Record<string, unknown>) {
+  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: string, options: MillionVerifierRequestOptions) {
+      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<TSchema extends z.ZodType>(
+  response: Response,
+  path: string,
+  schema: TSchema,
+  options?: { acceptErrorFieldWhenValid?: boolean },
+): Promise<z.output<TSchema>> {
+  const value: unknown = 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: 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}`
+  }
+}