@tokshare/pick 0.0.0-stage → 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,231 @@
+type ErrorCode = "bad_request" | "key_invalid" | "origin_not_allowed" | "rate_limited" | "quota_exceeded" | "not_found" | "unauthorized" | "already_claimed" | "expired" | "closed" | "limit_reached" | "file_too_large" | "session_too_large" | "type_rejected" | "size_mismatch" | "upload_incomplete" | "download_limit" | "network" | "internal";
+declare class PickError extends Error {
+    readonly code: ErrorCode;
+    readonly status: number;
+    constructor(code: ErrorCode, message?: string, status?: number);
+}
+
+type CloseReason = "desktop_closed" | "expired" | "limit_reached" | "phone_rejected" | "completed" | "error";
+type Locale = "en" | "ar";
+/** What a website may ask for. The relay clamps every number to the plan's limits. */
+interface SessionOptions {
+    /** Like <input accept>: "image/*,.pdf,application/zip". Empty means any file. */
+    accept?: string;
+    multiple?: boolean;
+    maxFiles?: number;
+    maxFileBytes?: number;
+    /** Phone shrinks photos before sending: longest side in pixels, JPEG quality 0–1. */
+    resizeImages?: {
+        maxDimension: number;
+        quality?: number;
+    } | false;
+    /** The phone waits until someone at the computer approves it. */
+    confirmPhone?: boolean;
+    locale?: Locale;
+    /** Shown on the phone: "<siteName> is asking for files". Defaults to the website's host. */
+    siteName?: string;
+    /** Send files straight from the phone to this page over the local network (WebRTC) when both are
+     *  on the same Wi-Fi, falling back to the cloud otherwise. Default true. */
+    direct?: boolean;
+}
+interface PhoneInfo {
+    /** Coarse: "iPhone · Safari", "Android · Chrome". */
+    label: string;
+}
+interface FileMeta {
+    id: string;
+    name: string;
+    size: number;
+    type: string;
+    lastModified: number;
+    /** The type found in the file's first bytes, when it could be recognized. */
+    sniffed?: string;
+}
+
+declare const en: {
+    title: string;
+    titleOne: string;
+    scan: string;
+    orType: string;
+    loading: string;
+    waiting: string;
+    connected: string;
+    connectedDirect: string;
+    disconnect: string;
+    phoneLeft: string;
+    approveTitle: string;
+    approveMatch: string;
+    approve: string;
+    reject: string;
+    sending: string;
+    receiving: string;
+    received: string;
+    failed: string;
+    cancel: string;
+    done: string;
+    useFiles: string;
+    useFile: string;
+    expired: string;
+    newCode: string;
+    error: string;
+    tryAgain: string;
+    close: string;
+    privacy: string;
+    dropTitle: string;
+    dropTitleOne: string;
+    dropActive: string;
+    or: string;
+    browse: string;
+    usePhone: string;
+    hintTypes: string;
+    hintAny: string;
+    hintCount: string;
+    phoneTitle: string;
+    phoneStep1: string;
+    phoneStep2: string;
+    phoneStep3: string;
+    phoneCode: string;
+    back: string;
+    doneWithPhone: string;
+    sourcePhone: string;
+    sourceDevice: string;
+    remove: string;
+    tooLarge: string;
+    wrongType: string;
+    tooMany: string;
+    fileCount: string;
+    clearAll: string;
+    announceText: string;
+    announceLink: string;
+    announceHide: string;
+};
+type Strings = typeof en;
+type StringKey = keyof Strings;
+
+interface PickOptions extends Omit<SessionOptions, "locale"> {
+    /** Your publishable key (pk_live_… or pk_test_…). */
+    key: string;
+    /** Relay URL. Defaults to the hosted relay. */
+    relay?: string;
+    /** "auto" follows the page's lang attribute, then the browser. */
+    locale?: Locale | "auto";
+    /** false: no modal; use the controller's events, claimUrl and code to build your own UI. */
+    ui?: boolean;
+    theme?: "light" | "dark" | "auto";
+    /** Replace any of the modal's strings. */
+    strings?: Partial<Record<StringKey, string>>;
+    /** A small, dismissible line about TokShare for desktop in the modal and the field. Default true. */
+    announce?: boolean;
+    signal?: AbortSignal;
+}
+interface ProgressInfo {
+    id: string;
+    name: string;
+    sent: number;
+    total: number;
+    /** "upload": phone → relay (or straight to this page over Wi-Fi). "download": relay → this page. */
+    phase: "upload" | "download";
+}
+interface PickEvents {
+    ready: {
+        claimUrl: string;
+        code: string;
+    };
+    phone: {
+        phone: PhoneInfo;
+        needsApproval: boolean;
+        match?: string;
+    };
+    phone_left: undefined;
+    /** The phone is on the same network and files come straight to this page (true), or not any more. */
+    direct: {
+        connected: boolean;
+    };
+    file_started: FileMeta;
+    progress: ProgressInfo;
+    file: File;
+    /** The same file, with the relay id its progress events used. */
+    received: {
+        id: string;
+        file: File;
+    };
+    file_failed: {
+        id: string;
+        code: string;
+    };
+    error: PickError;
+    close: CloseReason | "canceled" | "finished";
+}
+interface PickController {
+    /** Resolves with the received files when the person finishes; [] if canceled before any arrived. */
+    readonly done: Promise<File[]>;
+    /** Files received so far. */
+    readonly files: readonly File[];
+    readonly claimUrl: string | null;
+    readonly code: string | null;
+    on<E extends keyof PickEvents>(event: E, handler: (detail: PickEvents[E]) => void): () => void;
+    /** Use the files received so far. */
+    finish(): void;
+    /** Close without files. */
+    cancel(): void;
+    approve(): void;
+    reject(): void;
+    /** Forget the connected phone and show a new code. */
+    disconnect(): Promise<void>;
+    /** Start over with a new session (after an expiry or error). */
+    restart(): void;
+}
+declare function open(options: PickOptions): PickController;
+/** Opens the picker and resolves with the files the person sent ([] if they canceled). */
+declare function pick(options: PickOptions): Promise<File[]>;
+interface AttachOptions extends Omit<PickOptions, "accept" | "multiple"> {
+    /** "replace" (default) sets the input's files; "append" adds to what it already has. */
+    mode?: "replace" | "append";
+}
+/** Fills an existing <input type="file"> with files from the phone, firing input and change events,
+ *  so forms and frameworks that listen to the input keep working. Returns a function that does it. */
+declare function attach(input: HTMLInputElement, options: AttachOptions): () => Promise<File[]>;
+
+interface FieldOptions extends Omit<PickOptions, "ui"> {
+    /** Form field name: the files go into a hidden <input type="file" name> inside the target. */
+    name?: string;
+    /** "inline" (default): the phone flow opens inside the field. "modal": in a window. false: no phone. */
+    phone?: "inline" | "modal" | false;
+    /** Show "Use your phone" even when this page itself is open on a phone. */
+    phoneOnMobile?: boolean;
+    /** Replaces the drop zone's title. */
+    label?: string;
+}
+interface FieldController {
+    readonly files: readonly File[];
+    /** The hidden input the files are kept in (for forms and frameworks). */
+    readonly input: HTMLInputElement;
+    on(event: "change", handler: (files: File[]) => void): () => void;
+    remove(file: File): void;
+    clear(): void;
+    destroy(): void;
+}
+/** "5MB", "500 KB", "2e6" → bytes. */
+declare function parseSize(value: string | number | null | undefined): number | undefined;
+declare function mountField(target: HTMLElement | string, options: FieldOptions): FieldController;
+/** <tokshare-pick-field key name accept multiple max-files max-size phone locale theme relay label direct announce>.
+ *  direct="off" sends everything through the cloud; announce="off" hides the TokShare for desktop line. */
+declare function defineFieldElement(defaults?: Partial<FieldOptions>, tag?: string): void;
+
+/** The hosted relay. Override with the `relay` option or a script tag's data-relay attribute
+ *  (local development: "http://localhost:8788").
+ *  0.1.x uses the relay's workers.dev address; a later version moves to the TokShare domain. That
+ *  address must stay up for sites still on 0.1.x (wrangler.jsonc keeps workers_dev on). */
+declare const DEFAULT_RELAY = "https://tokshare-pick.pjturki.workers.dev";
+declare const SDK_VERSION = "0.1.1";
+
+/** The same functions as one object: TokSharePick.pick({ key }). */
+declare const TokSharePick: {
+    pick: typeof pick;
+    open: typeof open;
+    attach: typeof attach;
+    mountField: typeof mountField;
+    defineFieldElement: typeof defineFieldElement;
+};
+
+export { type AttachOptions, DEFAULT_RELAY, type ErrorCode, type FieldController, type FieldOptions, type FileMeta, type PhoneInfo, type PickController, PickError, type PickEvents, type PickOptions, type ProgressInfo, SDK_VERSION, TokSharePick, attach, defineFieldElement, mountField, open, parseSize, pick };

package/dist/index.d.ts

@@ -0,0 +1,231 @@
+type ErrorCode = "bad_request" | "key_invalid" | "origin_not_allowed" | "rate_limited" | "quota_exceeded" | "not_found" | "unauthorized" | "already_claimed" | "expired" | "closed" | "limit_reached" | "file_too_large" | "session_too_large" | "type_rejected" | "size_mismatch" | "upload_incomplete" | "download_limit" | "network" | "internal";
+declare class PickError extends Error {
+    readonly code: ErrorCode;
+    readonly status: number;
+    constructor(code: ErrorCode, message?: string, status?: number);
+}
+
+type CloseReason = "desktop_closed" | "expired" | "limit_reached" | "phone_rejected" | "completed" | "error";
+type Locale = "en" | "ar";
+/** What a website may ask for. The relay clamps every number to the plan's limits. */
+interface SessionOptions {
+    /** Like <input accept>: "image/*,.pdf,application/zip". Empty means any file. */
+    accept?: string;
+    multiple?: boolean;
+    maxFiles?: number;
+    maxFileBytes?: number;
+    /** Phone shrinks photos before sending: longest side in pixels, JPEG quality 0–1. */
+    resizeImages?: {
+        maxDimension: number;
+        quality?: number;
+    } | false;
+    /** The phone waits until someone at the computer approves it. */
+    confirmPhone?: boolean;
+    locale?: Locale;
+    /** Shown on the phone: "<siteName> is asking for files". Defaults to the website's host. */
+    siteName?: string;
+    /** Send files straight from the phone to this page over the local network (WebRTC) when both are
+     *  on the same Wi-Fi, falling back to the cloud otherwise. Default true. */
+    direct?: boolean;
+}
+interface PhoneInfo {
+    /** Coarse: "iPhone · Safari", "Android · Chrome". */
+    label: string;
+}
+interface FileMeta {
+    id: string;
+    name: string;
+    size: number;
+    type: string;
+    lastModified: number;
+    /** The type found in the file's first bytes, when it could be recognized. */
+    sniffed?: string;
+}
+
+declare const en: {
+    title: string;
+    titleOne: string;
+    scan: string;
+    orType: string;
+    loading: string;
+    waiting: string;
+    connected: string;
+    connectedDirect: string;
+    disconnect: string;
+    phoneLeft: string;
+    approveTitle: string;
+    approveMatch: string;
+    approve: string;
+    reject: string;
+    sending: string;
+    receiving: string;
+    received: string;
+    failed: string;
+    cancel: string;
+    done: string;
+    useFiles: string;
+    useFile: string;
+    expired: string;
+    newCode: string;
+    error: string;
+    tryAgain: string;
+    close: string;
+    privacy: string;
+    dropTitle: string;
+    dropTitleOne: string;
+    dropActive: string;
+    or: string;
+    browse: string;
+    usePhone: string;
+    hintTypes: string;
+    hintAny: string;
+    hintCount: string;
+    phoneTitle: string;
+    phoneStep1: string;
+    phoneStep2: string;
+    phoneStep3: string;
+    phoneCode: string;
+    back: string;
+    doneWithPhone: string;
+    sourcePhone: string;
+    sourceDevice: string;
+    remove: string;
+    tooLarge: string;
+    wrongType: string;
+    tooMany: string;
+    fileCount: string;
+    clearAll: string;
+    announceText: string;
+    announceLink: string;
+    announceHide: string;
+};
+type Strings = typeof en;
+type StringKey = keyof Strings;
+
+interface PickOptions extends Omit<SessionOptions, "locale"> {
+    /** Your publishable key (pk_live_… or pk_test_…). */
+    key: string;
+    /** Relay URL. Defaults to the hosted relay. */
+    relay?: string;
+    /** "auto" follows the page's lang attribute, then the browser. */
+    locale?: Locale | "auto";
+    /** false: no modal; use the controller's events, claimUrl and code to build your own UI. */
+    ui?: boolean;
+    theme?: "light" | "dark" | "auto";
+    /** Replace any of the modal's strings. */
+    strings?: Partial<Record<StringKey, string>>;
+    /** A small, dismissible line about TokShare for desktop in the modal and the field. Default true. */
+    announce?: boolean;
+    signal?: AbortSignal;
+}
+interface ProgressInfo {
+    id: string;
+    name: string;
+    sent: number;
+    total: number;
+    /** "upload": phone → relay (or straight to this page over Wi-Fi). "download": relay → this page. */
+    phase: "upload" | "download";
+}
+interface PickEvents {
+    ready: {
+        claimUrl: string;
+        code: string;
+    };
+    phone: {
+        phone: PhoneInfo;
+        needsApproval: boolean;
+        match?: string;
+    };
+    phone_left: undefined;
+    /** The phone is on the same network and files come straight to this page (true), or not any more. */
+    direct: {
+        connected: boolean;
+    };
+    file_started: FileMeta;
+    progress: ProgressInfo;
+    file: File;
+    /** The same file, with the relay id its progress events used. */
+    received: {
+        id: string;
+        file: File;
+    };
+    file_failed: {
+        id: string;
+        code: string;
+    };
+    error: PickError;
+    close: CloseReason | "canceled" | "finished";
+}
+interface PickController {
+    /** Resolves with the received files when the person finishes; [] if canceled before any arrived. */
+    readonly done: Promise<File[]>;
+    /** Files received so far. */
+    readonly files: readonly File[];
+    readonly claimUrl: string | null;
+    readonly code: string | null;
+    on<E extends keyof PickEvents>(event: E, handler: (detail: PickEvents[E]) => void): () => void;
+    /** Use the files received so far. */
+    finish(): void;
+    /** Close without files. */
+    cancel(): void;
+    approve(): void;
+    reject(): void;
+    /** Forget the connected phone and show a new code. */
+    disconnect(): Promise<void>;
+    /** Start over with a new session (after an expiry or error). */
+    restart(): void;
+}
+declare function open(options: PickOptions): PickController;
+/** Opens the picker and resolves with the files the person sent ([] if they canceled). */
+declare function pick(options: PickOptions): Promise<File[]>;
+interface AttachOptions extends Omit<PickOptions, "accept" | "multiple"> {
+    /** "replace" (default) sets the input's files; "append" adds to what it already has. */
+    mode?: "replace" | "append";
+}
+/** Fills an existing <input type="file"> with files from the phone, firing input and change events,
+ *  so forms and frameworks that listen to the input keep working. Returns a function that does it. */
+declare function attach(input: HTMLInputElement, options: AttachOptions): () => Promise<File[]>;
+
+interface FieldOptions extends Omit<PickOptions, "ui"> {
+    /** Form field name: the files go into a hidden <input type="file" name> inside the target. */
+    name?: string;
+    /** "inline" (default): the phone flow opens inside the field. "modal": in a window. false: no phone. */
+    phone?: "inline" | "modal" | false;
+    /** Show "Use your phone" even when this page itself is open on a phone. */
+    phoneOnMobile?: boolean;
+    /** Replaces the drop zone's title. */
+    label?: string;
+}
+interface FieldController {
+    readonly files: readonly File[];
+    /** The hidden input the files are kept in (for forms and frameworks). */
+    readonly input: HTMLInputElement;
+    on(event: "change", handler: (files: File[]) => void): () => void;
+    remove(file: File): void;
+    clear(): void;
+    destroy(): void;
+}
+/** "5MB", "500 KB", "2e6" → bytes. */
+declare function parseSize(value: string | number | null | undefined): number | undefined;
+declare function mountField(target: HTMLElement | string, options: FieldOptions): FieldController;
+/** <tokshare-pick-field key name accept multiple max-files max-size phone locale theme relay label direct announce>.
+ *  direct="off" sends everything through the cloud; announce="off" hides the TokShare for desktop line. */
+declare function defineFieldElement(defaults?: Partial<FieldOptions>, tag?: string): void;
+
+/** The hosted relay. Override with the `relay` option or a script tag's data-relay attribute
+ *  (local development: "http://localhost:8788").
+ *  0.1.x uses the relay's workers.dev address; a later version moves to the TokShare domain. That
+ *  address must stay up for sites still on 0.1.x (wrangler.jsonc keeps workers_dev on). */
+declare const DEFAULT_RELAY = "https://tokshare-pick.pjturki.workers.dev";
+declare const SDK_VERSION = "0.1.1";
+
+/** The same functions as one object: TokSharePick.pick({ key }). */
+declare const TokSharePick: {
+    pick: typeof pick;
+    open: typeof open;
+    attach: typeof attach;
+    mountField: typeof mountField;
+    defineFieldElement: typeof defineFieldElement;
+};
+
+export { type AttachOptions, DEFAULT_RELAY, type ErrorCode, type FieldController, type FieldOptions, type FileMeta, type PhoneInfo, type PickController, PickError, type PickEvents, type PickOptions, type ProgressInfo, SDK_VERSION, TokSharePick, attach, defineFieldElement, mountField, open, parseSize, pick };