@whop/elements 1.0.0-beta.2 → 1.0.0-beta.4

package/verifications.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Options for `whop.verifications.create()`: the controller's props plus its `on<Event>` callbacks. In React, these are the `<Verifications>` component's props.
+ * @example
+ * ```ts
+ * import { loadWhop } from "@whop/elements";
+ * 
+ * const whop = (await loadWhop())({ locale: "en" });
+ * const verifications = whop.verifications.create({}); // options: props + on<Event> callbacks
+ * ```
+ * @see https://docs.whop.com/elements/latest/verifications/overview
+ */
+export interface VerificationsOptions {
+	/**
+	 * Use `individual` for KYC or `business` for KYB. The mounted element owns the matching intake form.
+	 * @default "individual"
+	 */
+	kind?: "individual" | "business";
+	/**
+	 * The account being verified: a company `biz_…` tag or the viewer's own `user_…` tag.
+	 */
+	accountId: string;
+	/**
+	 * Called on your page before the element mounts. Return a fresh bearer credential with `identity:read` and `identity:write`; omit it only for a same-origin Whop session.
+	 */
+	getToken?: (() => Promise<string>);
+	/**
+	 * Runs when the grouped loading state changes. The value is `true` while any mounted element is still loading.
+	 */
+	onLoadingChange?: ((loading: boolean) => void);
+	/**
+	 * Set `false` to turn off Whop's built-in usage analytics for this handle and its elements. The analytics identity is never threaded to its frames. A reserved option, not element data.
+	 */
+	analytics?: false;
+	/**
+	 * Visual customization for this group's elements. Overrides the global `WhopElements({ appearance })`. Change it live with `update({ appearance })`.
+	 */
+	appearance?: import("./_framework.js").Appearance;
+	/**
+	 * Locale for this group's element UI text. Set it to one of the app's built locales to override the global configuration. Any other value falls back to the default locale.
+	 */
+	locale?: import("./_framework.js").WhopElementsLocale;
+}
+
+/**
+ * Consumer props for the "kyc" element. Set at create (or as `<KycElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/verifications/kyc
+ */
+export interface KycElementProps {}
+
+/**
+ * The live handle for a mounted "kyc" element. Returned by `create("kyc")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/verifications/kyc
+ */
+export interface KycElementHandle {
+	/**
+	 * Fetch the latest verification status immediately. Pending and review states also poll automatically.
+	 */
+	refresh: () => Promise<{ verificationId: string; status: "not_started" | "pending" | "processing" | "manual_review" | "approved" | "rejected" | "action_required"; } | null>;
+	/**
+	 * Abandon the current attempt and start a fresh hosted session immediately.
+	 */
+	restart: () => Promise<void>;
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<KycElementProps>) => void;
+}
+
+/**
+ * Options for `create("kyc")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const kyc = verifications.create("kyc", {}); // this interface: props + on<Event> callbacks
+ * kyc.mount("#verifications-kyc");
+ * ```
+ * @see https://docs.whop.com/elements/latest/verifications/kyc
+ */
+export interface KycElementCreateOptions {
+	/**
+	 * The verification entered a new status, including the status found on first mount.
+	 */
+	onStatusChanged?: ((payload: { verificationId: string; status: "not_started" | "pending" | "processing" | "manual_review" | "approved" | "rejected" | "action_required"; }) => void);
+	/**
+	 * Verification was approved. Fires once when the element first observes `approved`.
+	 */
+	onCompleted?: ((payload: { verificationId: string; }) => void);
+	/**
+	 * Whop needs follow-up information. The element renders and submits the requested fields itself.
+	 */
+	onActionRequired?: ((payload: { verificationId: string; requestedInformation: ActionRequiredItem[]; }) => void);
+	/**
+	 * The initial load, intake submission, follow-up submission, or an explicit restart failed.
+	 */
+	onLoadFailed?: ((payload: { reason: "access_denied" | "unavailable"; }) => void);
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * Consumer props for the "capabilities" element. Set at create (or as `<CapabilitiesElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/verifications/capabilities
+ */
+export interface CapabilitiesElementProps {
+	/**
+	 * Hide the individual and business verification rows, leaving only the capabilities.
+	 * @default false
+	 */
+	hideStatus?: boolean;
+	/**
+	 * Hide the capabilities list, leaving only the two verification rows.
+	 * @default false
+	 */
+	hideCapabilities?: boolean;
+}
+
+/**
+ * The live handle for a mounted "capabilities" element. Returned by `create("capabilities")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/verifications/capabilities
+ */
+export interface CapabilitiesElementHandle {
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<CapabilitiesElementProps>) => void;
+}
+
+/**
+ * Options for `create("capabilities")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const capabilities = verifications.create("capabilities", {}); // this interface: props + on<Event> callbacks
+ * capabilities.mount("#verifications-capabilities");
+ * ```
+ * @see https://docs.whop.com/elements/latest/verifications/capabilities
+ */
+export interface CapabilitiesElementCreateOptions {
+	/**
+	 * Hide the individual and business verification rows, leaving only the capabilities.
+	 * @default false
+	 */
+	hideStatus?: boolean;
+	/**
+	 * Hide the capabilities list, leaving only the two verification rows.
+	 * @default false
+	 */
+	hideCapabilities?: boolean;
+	/**
+	 * The viewer pressed a verify button. The element never navigates — mount your own verification, such as this namespace’s `kyc` element, in answer to this.
+	 */
+	onVerificationRequested?: ((payload: { accountId: string; kind: "individual" | "business"; }) => void);
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * Consumer props for the "rfi" element. Set at create (or as `<RfiElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/verifications/rfi
+ */
+export interface RfiElementProps {
+	/**
+	 * Hide the rows that are already with a reviewer, leaving only what the viewer can act on.
+	 * @default false
+	 */
+	hideUnderReview?: boolean;
+}
+
+/**
+ * The live handle for a mounted "rfi" element. Returned by `create("rfi")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/verifications/rfi
+ */
+export interface RfiElementHandle {
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<RfiElementProps>) => void;
+}
+
+/**
+ * Options for `create("rfi")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const rfi = verifications.create("rfi", {}); // this interface: props + on<Event> callbacks
+ * rfi.mount("#verifications-rfi");
+ * ```
+ * @see https://docs.whop.com/elements/latest/verifications/rfi
+ */
+export interface RfiElementCreateOptions {
+	/**
+	 * Hide the rows that are already with a reviewer, leaving only what the viewer can act on.
+	 * @default false
+	 */
+	hideUnderReview?: boolean;
+	/**
+	 * One group of requirements was answered. Fires per group, not once per field.
+	 */
+	onSubmitted?: ((payload: { source: "identity" | "payout" | "audit" | "card_issuing" | "bank" | "ads" | "application" | "airwallex"; itemIds: string[]; }) => void);
+	/**
+	 * Nothing is outstanding any more. Fires when the element first observes an empty list, including on mount.
+	 */
+	onCompleted?: ((payload: { accountId: string; }) => void);
+	/**
+	 * The outstanding requests could not be read, or answering one failed.
+	 */
+	onLoadFailed?: ((payload: { reason: "access_denied" | "unavailable"; }) => void);
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * The Verifications handle, returned by `whop.verifications.create()` (React: `useVerifications()`). Mounts the elements and carries the controller's actions.
+ * @see https://docs.whop.com/elements/latest/verifications/overview
+ */
+export interface VerificationsHandle {
+	/**
+	 * A complete identity-verification flow. It collects individual KYC or business KYB details, starts or resumes the hosted provider session, handles follow-up information and document requests, polls status, and renders the final result without requiring the host to build verification UI.
+	 */
+	create(name: "kyc", options?: KycElementCreateOptions): KycElementHandle;
+	/**
+	 * The account's verification standing: whether individual and business verification are done, and which capabilities that unlocks. Read-only — pressing a verify button reports `verificationRequested` and stays put, so the host mounts its own flow, such as this namespace's `kyc` element. Both halves can be hidden, so a host that only wants the capability list, or only the two verification rows, can drop the other.
+	 */
+	create(name: "capabilities", options?: CapabilitiesElementCreateOptions): CapabilitiesElementHandle;
+	/**
+	 * Everything the account still owes compliance, and the forms to answer it. Each row is one group of requirements — grouped by the system that asked, because each relays to its provider once its own items are answered — and pressing it opens that group’s form in place. Rows already with a reviewer are shown but not answerable. Renders an all-clear once nothing is outstanding, so it can sit permanently in a settings page.
+	 */
+	create(name: "rfi", options?: RfiElementCreateOptions): RfiElementHandle;
+	/**
+	 * Merges new handle options into every mounted element. In React, change the namespace props instead.
+	 */
+	update(options: Partial<VerificationsOptions>): void;
+	/**
+	 * Destroys every element and sub-controller this handle created, removes the controller frame, and releases its subscriptions. You can call it more than once, but a destroyed handle refuses any other call — create a new handle to start over. React removes the group automatically when the provider unmounts.
+	 */
+	destroy(): void;
+}
+
+/**
+ * Verifications's static actions, callable with nothing mounted: `whop.verifications.<method>()` (React: `useWhop().verifications.<method>()`).
+ * @see https://docs.whop.com/elements/latest/verifications/overview
+ */
+export interface VerificationsStatics {}
+
+/**
+ * Declared from the app's `ActionRequiredItem`, referenced by a host-capability surface.
+ */
+export interface ActionRequiredItem {
+	id: string;
+	requirement: string;
+	type: string;
+	label: string;
+	source?: "identity" | "payout" | "audit" | "card_issuing" | "bank" | "ads" | "application" | undefined;
+	optional?: boolean | undefined;
+	options?: string[] | undefined;
+	errors?: { code: string; reason: string; }[] | undefined;
+}