diff --git a/types/clearoutio__clearout/.npmignore b/types/clearoutio__clearout/.npmignore new file mode 100644 index 00000000000000..93e307400a5456 --- /dev/null +++ b/types/clearoutio__clearout/.npmignore @@ -0,0 +1,5 @@ +* +!**/*.d.ts +!**/*.d.cts +!**/*.d.mts +!**/*.d.*.ts diff --git a/types/clearoutio__clearout/clearoutio__clearout-tests.ts b/types/clearoutio__clearout/clearoutio__clearout-tests.ts new file mode 100644 index 00000000000000..29ab5f73934935 --- /dev/null +++ b/types/clearoutio__clearout/clearoutio__clearout-tests.ts @@ -0,0 +1,175 @@ +import Clearout = require("@clearoutio/clearout"); + +// Construct with `new` and a config object. +const client = new Clearout("api-token", { timeout: 15000 }); + +// Construct by calling the factory directly (CommonJS style, no `new`). +const factoryClient = Clearout("api-token"); + +// Full config object. +const configured = new Clearout("api-token", { + timeout: 5000, + optimize: "highest_accuracy", + ignore_result: true, + ignore_duplicate_file: "false", + queue: true, +}); + +// @ts-expect-error - token is required. +new Clearout(); + +// @ts-expect-error - optimize must be one of the allowed strings. +new Clearout("api-token", { optimize: "fastest" }); + +// Mirrors real-world usage: dynamic import + default interop. +async function defaultClearoutVerify(email: string): Promise { + const { default: ClearoutDefault } = await import("@clearoutio/clearout"); + const c = new ClearoutDefault("api-token", { timeout: 15000 }); + return c.emailVerifier.verify({ email }); +} + +async function verifierExamples() { + // $ExpectType InstantVerifyResult + const result = await client.emailVerifier.verify({ email: "elon.musk@tesla.com" }); + // $ExpectType SafeToSend + result.safe_to_send; + // $ExpectType string + result.status; + // $ExpectType YesNo + result.disposable; + // $ExpectType number + result.sub_status.code; + // $ExpectType string + result.detail_info.domain; + + // timeout is optional and overridable. + await client.emailVerifier.verify({ email: "test@example.com", timeout: 90000 }); + + // @ts-expect-error - email is required. + await client.emailVerifier.verify({}); + + // $ExpectType BulkListResult + const bulk = await client.emailVerifier.bulkVerify({ + file: "/tmp/emails.csv", + optimize: "fastest_turnaround", + ignore_duplicate_file: "true", + }); + // $ExpectType string + bulk.list_id; + + // $ExpectType BulkVerifyProgressStatus + const progress = await client.emailVerifier.getBulkVerifyProgressStatus({ list_id: bulk.list_id }); + // $ExpectType number | undefined + progress.percentile; + // @ts-expect-error - percentage is a bulk-finder field, not a bulk-verify one. + progress.percentage; + + // $ExpectType DownloadResult + const download = await client.emailVerifier.downloadBulkVerifyResult({ list_id: bulk.list_id }); + // $ExpectType string + download.url; + + // $ExpectType ListActionResult + const removed = await client.emailVerifier.removeBulkVerifyList({ list_id: bulk.list_id, ignore_result: true }); + // $ExpectType string + removed.name; + + // $ExpectType ListActionResult + await client.emailVerifier.cancelBulkVerifyList({ list_id: bulk.list_id }); + + // $ExpectType CatchAllResult + const catchAll = await client.emailVerifier.isCatchAllEmail({ email: "mike.k@shopify.com" }); + // $ExpectType YesNo + catchAll.catchall; + + // $ExpectType DisposableResult + const disposable = await client.emailVerifier.isDisposableEmail({ email: "john@temp-mail.org" }); + // $ExpectType YesNo + disposable.disposable; + + // $ExpectType BusinessResult + const business = await client.emailVerifier.isBusinessEmail({ email: "us@clearout.io" }); + // $ExpectType YesNo + business.business_account; + + // $ExpectType FreeResult + const free = await client.emailVerifier.isFreeEmail({ email: "john@gmail.com" }); + // $ExpectType YesNo + free.free_account; + + // $ExpectType RoleResult + const role = await client.emailVerifier.isRoleEmail({ email: "info@gmail.com" }); + // $ExpectType YesNo + role.role_account; + + // $ExpectType GibberishResult + const gibberish = await client.emailVerifier.isGibberishEmail({ email: "abcd12345@gmail.com" }); + // $ExpectType YesNo + gibberish.gibberish; +} + +async function finderExamples() { + // $ExpectType EmailFinderResult + const found = await client.emailFinder.find({ + name: "Elon Musk", + domain: "tesla.com", + timeout: 10000, + queue: true, + }); + // $ExpectType string + found.emails[0].email_address; + // $ExpectType number + found.confidence_score; + // $ExpectType string + found.company.name; + + // domain is required. + // @ts-expect-error + await client.emailFinder.find({ name: "Elon Musk" }); + + // $ExpectType EmailFinderStatusResult + const status = await client.emailFinder.getStatus({ qid: "61008c4597947d45700f4bb2" }); + if ("emails" in status) { + // Completed: the full found-email payload is available. + // $ExpectType FoundEmail[] + status.emails; + // $ExpectType number + status.confidence_score; + } else { + // Still queued: only the progress status is available. + // $ExpectType string + status.query_status; + // @ts-expect-error - found-email fields are not present while queued. + status.emails; + } + + // $ExpectType BulkListResult + const bulk = await client.emailFinder.bulkFind({ file: "/tmp/people.csv", ignore_duplicate_file: "true" }); + + // $ExpectType BulkFinderProgressStatus + const progress = await client.emailFinder.getBulkFindProgressStatus({ list_id: bulk.list_id }); + // $ExpectType number | undefined + progress.percentage; + // @ts-expect-error - percentile is a bulk-verify field, not a bulk-finder one. + progress.percentile; + + // $ExpectType DownloadResult + await client.emailFinder.downloadBulkFindResult({ list_id: bulk.list_id }); + + // $ExpectType ListActionResult + await client.emailFinder.removeBulkFindList({ list_id: bulk.list_id }); + + // $ExpectType ListActionResult + await client.emailFinder.cancelBulkFinderList({ list_id: bulk.list_id }); +} + +async function accountExamples() { + // $ExpectType CreditsResult + const credits = await client.getCredits(); + // $ExpectType number + credits.available_credits; + // $ExpectType string | null + credits.credits.subs; + // $ExpectType number + credits.credits.total; +} diff --git a/types/clearoutio__clearout/index.d.ts b/types/clearoutio__clearout/index.d.ts new file mode 100644 index 00000000000000..c736567013a42f --- /dev/null +++ b/types/clearoutio__clearout/index.d.ts @@ -0,0 +1,427 @@ +/** + * Clearout Node.js client — a wrapper over the Clearout REST API + * (https://docs.clearout.io) for real-time and bulk email verification and + * email discovery. + * + * The module export is both callable and constructable: + * + * ```js + * const clearout = require("@clearoutio/clearout")("api-token", { timeout: 5000 }); + * // or + * import Clearout from "@clearoutio/clearout"; + * const clearout = new Clearout("api-token", { timeout: 5000 }); + * ``` + */ +declare const Clearout: Clearout.ClearoutStatic; + +declare namespace Clearout { + /** Optimization strategy for a bulk email verification request. */ + type Optimize = "highest_accuracy" | "fastest_turnaround"; + + /** + * Stringified boolean used by the API for the `ignore_duplicate_file` + * option (note: this is a string, not a boolean). + */ + type BooleanString = "true" | "false"; + + /** A `"yes"` / `"no"` flag as returned by the verification endpoints. */ + type YesNo = "yes" | "no"; + + /** Whether an email address is safe to send to. */ + type SafeToSend = "yes" | "no" | "risky"; + + /** + * Service-level configuration. Every option can be overridden per call when + * invoking a specific service method. + */ + interface ClearoutConfig { + /** + * Maximum time (in milliseconds) each request can take. + * @default 130000 // email verifier + * @default 30000 // email finder + */ + timeout?: number | undefined; + /** + * Bulk email verification optimization strategy. + * @default "highest_accuracy" + */ + optimize?: Optimize | undefined; + /** + * Ignore the result file even if it has not been downloaded. Used when + * removing a bulk list. + * @default false + */ + ignore_result?: boolean | undefined; + /** + * Whether to allow uploading a file whose name and size match a recent + * upload. + * @default "false" + */ + ignore_duplicate_file?: BooleanString | undefined; + /** + * For the email finder: whether discovery may continue in the + * background after the request times out. + * @default true + */ + queue?: boolean | undefined; + } + + /** Parameters for an instant verification / attribute-check request. */ + interface VerifyEmailParams { + /** Email address to verify. */ + email: string; + /** Overridable request timeout in milliseconds. */ + timeout?: number | undefined; + } + + /** Parameters for a bulk email verification request. */ + interface BulkVerifyParams { + /** Absolute path to the file containing the email addresses to upload. */ + file: string; + /** Optimization strategy. Defaults to the service-level config. */ + optimize?: Optimize | undefined; + /** Whether to allow a duplicate file upload. Defaults to the service-level config. */ + ignore_duplicate_file?: BooleanString | undefined; + } + + /** Parameters for an instant email finder request. */ + interface FindEmailParams { + /** Name of the person, e.g. `"Tony Stark"`. */ + name: string; + /** Domain or company name, e.g. `"marvel.com"` or `"Marvel Entertainment"`. */ + domain: string; + /** Overridable request timeout in milliseconds. */ + timeout?: number | undefined; + /** + * Whether email discovery may continue in the background after the + * request times out. Defaults to the service-level config. + */ + queue?: boolean | undefined; + } + + /** Parameters for a bulk email finder request. */ + interface BulkFindParams { + /** Absolute path to the file containing the people/domains to upload. */ + file: string; + /** Whether to allow a duplicate file upload. Defaults to the service-level config. */ + ignore_duplicate_file?: BooleanString | undefined; + } + + /** Parameters that reference a bulk list by id. */ + interface ListIdParams { + /** Id of the bulk list. */ + list_id: string; + } + + /** Parameters for removing a bulk list. */ + interface RemoveListParams { + /** Id of the bulk list to remove. */ + list_id: string; + /** + * Ignore the result file even if it has not been downloaded. Defaults + * to the service-level config. + */ + ignore_result?: boolean | undefined; + } + + /** Parameters for querying an instant email finder queue. */ + interface QueueStatusParams { + /** Queue id received from an instant email finder response. */ + qid: string; + } + + /** Additional details about an instant verification result. */ + interface VerifySubStatus { + /** Numeric sub-status code. */ + code: number; + /** Human-readable sub-status description. */ + desc: string; + } + + /** Parsed components of the verified email address. */ + interface VerifyDetailInfo { + /** Local part (account) of the email address. */ + account: string; + /** Domain part of the email address. */ + domain: string; + } + + /** Result of an instant email verification. */ + interface InstantVerifyResult { + /** The verified email address. */ + email_address: string; + /** Whether the address is safe to send to. */ + safe_to_send: SafeToSend; + /** Deliverability status, e.g. `"valid"`, `"invalid"`, `"unknown"`. */ + status: string; + /** ISO timestamp of when the address was verified. */ + verified_on: string; + /** Time taken to verify, in milliseconds. */ + time_taken: number; + /** Additional status detail. */ + sub_status: VerifySubStatus; + /** Parsed components of the email address. */ + detail_info: VerifyDetailInfo; + /** Blacklists the address or its domain was found on, if any. */ + blacklist_info?: string[] | undefined; + /** Whether the address is disposable/temporary. */ + disposable: YesNo; + /** Whether the address belongs to a free email provider. */ + free: YesNo; + /** Whether the address is a role/group account. */ + role: YesNo; + /** Whether the address looks gibberish. */ + gibberish: YesNo; + /** A corrected address when a typo is detected. */ + suggested_email_address?: string | undefined; + /** Reserved for profile information. */ + profile?: string | null | undefined; + /** Confidence score. */ + score?: number | undefined; + /** Bounce classification, when available. */ + bounce_type?: string | undefined; + } + + /** Result of a catch-all check. */ + interface CatchAllResult { + email_address: string; + catchall: YesNo; + verified_on: string; + time_taken: number; + } + + /** Result of a disposable-address check. */ + interface DisposableResult { + email_address: string; + disposable: YesNo; + verified_on: string; + time_taken: number; + } + + /** Result of a business-account check. */ + interface BusinessResult { + email_address: string; + business_account: YesNo; + verified_on: string; + time_taken: number; + } + + /** Result of a free-account check. */ + interface FreeResult { + email_address: string; + free_account: YesNo; + verified_on: string; + time_taken: number; + } + + /** Result of a role-account check. */ + interface RoleResult { + email_address: string; + role_account: YesNo; + verified_on: string; + time_taken: number; + } + + /** Result of a gibberish-account check. */ + interface GibberishResult { + email_address: string; + gibberish: YesNo; + verified_on: string; + time_taken: number; + } + + /** Result of a bulk verify/find submission. */ + interface BulkListResult { + /** Id of the created bulk list. */ + list_id: string; + } + + /** Progress status of a running bulk verify list. */ + interface BulkVerifyProgressStatus { + /** Progress stage, e.g. `"running"` or `"completed"`. */ + progress_status: string; + /** Completion percentage. */ + percentile?: number | undefined; + } + + /** Progress status of a running bulk finder list. */ + interface BulkFinderProgressStatus { + /** Progress stage, e.g. `"running"` or `"completed"`. */ + progress_status: string; + /** Completion percentage. */ + percentage?: number | undefined; + } + + /** Result of a bulk result-download request. */ + interface DownloadResult { + /** Signed URL to download the result file. */ + url: string; + } + + /** Result of a bulk list removal / cancellation. */ + interface ListActionResult { + /** Id of the affected list, when returned. */ + list_id?: string | undefined; + /** Name of the uploaded file. */ + name: string; + /** Source of the list, e.g. `"upload"`. */ + source?: string | undefined; + /** ISO timestamp of when the list was created. */ + created_on?: string | undefined; + } + + /** A single email discovered by the email finder. */ + interface FoundEmail { + /** The discovered email address. */ + email_address: string; + /** Whether the address is a role/group account. */ + role: string; + /** Whether the address is a business address. */ + business: string; + } + + /** Company details attached to an email finder result. */ + interface FinderCompany { + /** Company name. */ + name: string; + } + + /** Result of a completed instant email finder request. */ + interface EmailFinderResult { + /** Discovered email addresses, ordered by confidence. */ + emails: FoundEmail[]; + /** First name of the person. */ + first_name: string; + /** Last name of the person. */ + last_name: string; + /** Full name of the person. */ + full_name: string; + /** Domain searched. */ + domain: string; + /** Confidence score of the top match (0-100). */ + confidence_score: number; + /** Number of addresses discovered. */ + total: number; + /** Company details. */ + company: FinderCompany; + /** ISO timestamp of when the address was found. */ + found_on: string; + /** Queue status, when the result is fetched via `getStatus`. */ + query_status?: string | undefined; + } + + /** + * Progress-only payload returned by {@link EmailFinder.getStatus} while + * the queued finder request has not completed yet. + */ + interface EmailFinderQueueStatus { + /** Current status of the queued finder request. */ + query_status: string; + } + + /** + * Result of a queue-status lookup: the discovered emails once the request + * completes, or a progress-only payload while it is still queued. + */ + type EmailFinderStatusResult = EmailFinderResult | EmailFinderQueueStatus; + + /** Available credits and quota details for the account. */ + interface CreditsResult { + /** Total available credits. */ + available_credits: number; + /** Detailed credit breakdown. */ + credits: { + /** Currently available credits. */ + available: number; + /** Subscription details, if any. */ + subs: string | null; + /** Remaining daily verify limit, if any. */ + available_daily_verify_limit: string | null; + /** When the daily verify limit resets, if any. */ + reset_daily_verify_limit_date: string | null; + /** Total credits. */ + total: number; + }; + /** Threshold at which a low-credit balance is flagged. */ + low_credit_balance_min_threshold: number; + } + + /** Email verification service, exposed as `clearout.emailVerifier`. */ + interface EmailVerifier { + /** Instantly verify a single email address. */ + verify(params: VerifyEmailParams): Promise; + /** Verify email addresses in bulk by uploading a file. */ + bulkVerify(params: BulkVerifyParams): Promise; + /** Get the progress status of a bulk verify request. */ + getBulkVerifyProgressStatus(params: ListIdParams): Promise; + /** Get the signed download URL for a completed bulk verify result. */ + downloadBulkVerifyResult(params: ListIdParams): Promise; + /** Remove a bulk verify list. */ + removeBulkVerifyList(params: RemoveListParams): Promise; + /** Cancel a running bulk verify list. */ + cancelBulkVerifyList(params: ListIdParams): Promise; + /** Check whether an address belongs to a catch-all domain. */ + isCatchAllEmail(params: VerifyEmailParams): Promise; + /** Check whether an address is disposable/temporary. */ + isDisposableEmail(params: VerifyEmailParams): Promise; + /** Check whether an address belongs to a business account. */ + isBusinessEmail(params: VerifyEmailParams): Promise; + /** Check whether an address belongs to a free email provider. */ + isFreeEmail(params: VerifyEmailParams): Promise; + /** Check whether an address is a role/group account. */ + isRoleEmail(params: VerifyEmailParams): Promise; + /** Check whether an address looks gibberish. */ + isGibberishEmail(params: VerifyEmailParams): Promise; + } + + /** Email finder service, exposed as `clearout.emailFinder`. */ + interface EmailFinder { + /** Instantly discover a person's email address. */ + find(params: FindEmailParams): Promise; + /** Get the status of a queued instant email finder request. */ + getStatus(params: QueueStatusParams): Promise; + /** Discover email addresses in bulk by uploading a file. */ + bulkFind(params: BulkFindParams): Promise; + /** Get the progress status of a bulk find request. */ + getBulkFindProgressStatus(params: ListIdParams): Promise; + /** Get the signed download URL for a completed bulk find result. */ + downloadBulkFindResult(params: ListIdParams): Promise; + /** Remove a bulk find list. */ + removeBulkFindList(params: RemoveListParams): Promise; + /** Cancel a running bulk find list. */ + cancelBulkFinderList(params: ListIdParams): Promise; + } + + /** A configured Clearout client instance. */ + interface ClearoutClient { + /** Email verification service. */ + emailVerifier: EmailVerifier; + /** Email finder service. */ + emailFinder: EmailFinder; + /** Get the account's available credits. */ + getCredits(): Promise; + } + + /** + * The module export. Call it as a function or with `new` to create a + * {@link ClearoutClient}. + */ + interface ClearoutStatic { + /** + * Create a client instance. + * @param token Clearout server-app API token. + * @param config Optional service-level configuration. + */ + (token: string, config?: ClearoutConfig): ClearoutClient; + /** + * Create a client instance. + * @param token Clearout server-app API token. + * @param config Optional service-level configuration. + */ + new(token: string, config?: ClearoutConfig): ClearoutClient; + /** Self-reference exposed for interop with ES-module default imports. */ + default: ClearoutStatic; + } +} + +export = Clearout; diff --git a/types/clearoutio__clearout/package.json b/types/clearoutio__clearout/package.json new file mode 100644 index 00000000000000..a25b3d084c23a2 --- /dev/null +++ b/types/clearoutio__clearout/package.json @@ -0,0 +1,17 @@ +{ + "private": true, + "name": "@types/clearoutio__clearout", + "version": "1.1.9999", + "projects": [ + "https://github.com/clearoutio/clearout-node" + ], + "devDependencies": { + "@types/clearoutio__clearout": "workspace:." + }, + "owners": [ + { + "name": "Usman S.", + "githubUsername": "max-programming" + } + ] +} diff --git a/types/clearoutio__clearout/tsconfig.json b/types/clearoutio__clearout/tsconfig.json new file mode 100644 index 00000000000000..241407cd98bb97 --- /dev/null +++ b/types/clearoutio__clearout/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "lib": [ + "es6" + ], + "module": "node16", + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "clearoutio__clearout-tests.ts" + ] +}