@open-apime/sdk 0.2.2

package/dist/index.d.cts

@@ -0,0 +1,512 @@
+import { A as ApimeError } from './index-37ITjlwO.cjs';
+export { a as ApiError, b as AuthenticationError, C as ConfigurationError, c as ConflictError, d as ConnectionError, I as InvalidRequestError, e as InvalidSignatureError, N as NotFoundError, P as PermissionError, R as RateLimitError, S as SessionUnavailableError, T as TimeoutError, U as UnprocessableError, f as constructEvent, v as verifyWebhookSignature } from './index-37ITjlwO.cjs';
+import { Instance, QrCode, EventLogEntry, InstanceInfo, Profile, SentMessage } from './types/index.cjs';
+export { C as ChatPresencePayload, a as ContactReachoutLockedPayload, b as ContactUpdatePayload, D as DisconnectedPayload, M as MessageButton, c as MessagePayload, P as PresencePayload, R as ReceiptPayload, d as RestrictionLiftedPayload, T as TemporaryBanPayload, W as WebhookEnvelope, e as WebhookEvent, f as WebhookEventType } from './events-BV5UVoFu.cjs';
+
+/**
+ * The apime has three credentials and they do not overlap: 46 routes only
+ * accept an instance token, 13 only accept a user one. Typing the credential
+ * lets the compiler refuse the wrong call, instead of the caller finding out
+ * with a 403 in production.
+ */
+/** Session token from POST /auth/login. Expires. */
+interface UserJwtAuth {
+    readonly type: "userJwt";
+    readonly token: string;
+}
+/** Integration token an admin creates. Does not expire. */
+interface ApiTokenAuth {
+    readonly type: "apiToken";
+    readonly token: string;
+}
+/**
+ * Scoped to a single instance, so the id travels with the credential and the
+ * caller never has to repeat it on every call.
+ */
+interface InstanceTokenAuth {
+    readonly type: "instanceToken";
+    readonly token: string;
+    readonly instanceId: string;
+}
+type Auth = UserJwtAuth | ApiTokenAuth | InstanceTokenAuth;
+/** The two credentials that identify a user, as opposed to a single instance. */
+type UserAuth = UserJwtAuth | ApiTokenAuth;
+type AuthKind = Auth["type"];
+
+/** What the SDK knows about a request when it reports it. */
+interface RequestInfo {
+    method: string;
+    /** Templated path, with ids replaced, so it groups in the error tracker. */
+    route: string;
+    /** Real path, with ids. Useful to reproduce the call. */
+    path: string;
+    instanceId: string | undefined;
+    attempt: number;
+    idempotencyKey: string | undefined;
+}
+interface SuccessInfo extends RequestInfo {
+    status: number;
+    durationMs: number;
+}
+interface FailureInfo extends RequestInfo {
+    status: number | undefined;
+    durationMs: number;
+    error: ApimeError;
+    /** True when the client is about to try again. */
+    willRetry: boolean;
+}
+/**
+ * Where the host app plugs its own observability. The SDK reports, and stays
+ * out of the decision: a library that imports Sentry forces it on everyone and
+ * pins a version the app may not want.
+ *
+ * Wiring these to the app's own logger is what makes reporting automatic for
+ * every call, instead of each call site remembering to try/catch.
+ */
+interface Observer {
+    onRequest?: (info: RequestInfo) => void;
+    onSuccess?: (info: SuccessInfo) => void;
+    /**
+     * Fires on every failed attempt, including the ones that will be retried.
+     * Check `willRetry` to report only what actually failed for good.
+     */
+    onError?: (info: FailureInfo) => void;
+    onRetry?: (info: FailureInfo & {
+        delayMs: number;
+    }) => void;
+}
+
+/** True when the app has an initialized Sentry. Absent means every report is a no-op. */
+declare function hasSentry(): boolean;
+
+interface RequestOptions {
+    timeoutMs?: number;
+    maxRetries?: number;
+    signal?: AbortSignal;
+    /** Extra headers for this call. */
+    headers?: Record<string, string>;
+    /**
+     * Makes a repeated send safe: the apime replays the first result instead of
+     * sending the message again. Required for a send to be retried at all.
+     */
+    idempotencyKey?: string;
+}
+interface HttpClientOptions {
+    baseUrl: string;
+    auth: Auth;
+    timeoutMs?: number;
+    maxRetries?: number;
+    fetch?: typeof globalThis.fetch;
+    /** Appended to the User-Agent, to identify the calling app in the apime logs. */
+    appName?: string;
+    /** Where the app plugs its logger or error tracker. See Observer. */
+    observer?: Observer;
+    /**
+     * With no observer, definitive failures still reach the Sentry the app
+     * already runs, found through its global client. No Sentry means no-op.
+     * Set false to silence it.
+     */
+    autoReport?: boolean;
+}
+interface SendArgs {
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    path: string;
+    query?: Record<string, string | number | undefined>;
+    body?: unknown;
+    options?: RequestOptions;
+}
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly auth;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    private readonly userAgent;
+    private readonly observer;
+    private readonly autoReport;
+    private readonly instanceId;
+    constructor(options: HttpClientOptions);
+    private info;
+    request<T>(args: SendArgs): Promise<T>;
+    /**
+     * A write is only retried when the caller passed an idempotency key: without
+     * it a retried send can deliver the same WhatsApp message twice. The one
+     * exception is 503, which the apime returns before touching WhatsApp.
+     */
+    private mayRetry;
+    private writeIsSafe;
+    private attempt;
+}
+
+interface CreateInstanceInput {
+    name: string;
+    webhook_url?: string;
+    webhook_secret?: string;
+}
+interface UpdateInstanceInput {
+    name: string;
+    webhook_url?: string | null;
+    webhook_secret?: string | null;
+}
+/**
+ * Routes that only a user credential reaches. An instance token gets a 403 here,
+ * so these live on the user client alone.
+ */
+declare class InstancesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(options?: RequestOptions): Promise<Instance[]>;
+    create(input: CreateInstanceInput, options?: RequestOptions): Promise<Instance>;
+    get(instanceId: string, options?: RequestOptions): Promise<Instance>;
+    update(instanceId: string, input: UpdateInstanceInput, options?: RequestOptions): Promise<Instance>;
+    delete(instanceId: string, options?: RequestOptions): Promise<void>;
+    rotateToken(instanceId: string, options?: RequestOptions): Promise<{
+        token: string;
+    }>;
+    getQrCode(instanceId: string, options?: RequestOptions): Promise<QrCode>;
+    disconnect(instanceId: string, options?: RequestOptions): Promise<{
+        message: string;
+    }>;
+    listEvents(instanceId: string, query?: {
+        limit?: number;
+    }, options?: RequestOptions): Promise<EventLogEntry[]>;
+}
+/**
+ * The same family seen from an instance token: the id comes from the credential
+ * and the routes are the ones that demand it.
+ */
+declare class ScopedInstanceResource {
+    private readonly http;
+    private readonly instanceId;
+    constructor(http: HttpClient, instanceId: string);
+    get(options?: RequestOptions): Promise<Instance>;
+    /** Only reachable with an instance token; a user token gets a 403. */
+    info(options?: RequestOptions): Promise<InstanceInfo>;
+    getQrCode(options?: RequestOptions): Promise<QrCode>;
+    disconnect(options?: RequestOptions): Promise<{
+        message: string;
+    }>;
+    listEvents(query?: {
+        limit?: number;
+    }, options?: RequestOptions): Promise<EventLogEntry[]>;
+    getProfile(jid: string, options?: RequestOptions): Promise<Profile>;
+    getBusinessProfile(jid: string, options?: RequestOptions): Promise<Profile>;
+    getProfilePicture(jid: string, options?: RequestOptions): Promise<{
+        url?: string;
+    }>;
+}
+
+/** Fields every send accepts to quote another message. */
+interface QuoteInput {
+    /** Id of the quoted message. */
+    quoted?: string;
+    quotedParticipant?: string;
+    quotedText?: string;
+    quotedFromMe?: boolean;
+}
+/** Marks the incoming message as read in the same call that answers it. */
+interface MarkReadInput {
+    markReadMessageId?: string;
+    markReadSender?: string;
+}
+interface SendTextInput extends QuoteInput, MarkReadInput {
+    to: string;
+    text: string;
+    mentionedJids?: string[];
+}
+interface SendMediaInput extends QuoteInput, MarkReadInput {
+    to: string;
+    type: "image" | "video";
+    /** Bytes of the file. The SDK does not read from disk. */
+    file: Blob | File;
+    filename?: string;
+    caption?: string;
+}
+interface SendAudioInput extends QuoteInput, MarkReadInput {
+    to: string;
+    file: Blob | File;
+    filename?: string;
+    /** true sends it as a voice note instead of an attachment. */
+    ptt?: boolean;
+    seconds?: number;
+}
+interface SendDocumentInput extends QuoteInput, MarkReadInput {
+    to: string;
+    file: Blob | File;
+    /** Name the recipient sees. */
+    filename?: string;
+    caption?: string;
+}
+interface ContactEntry {
+    displayName: string;
+    vcard?: string;
+}
+interface SendContactInput extends QuoteInput {
+    to: string;
+    displayName: string;
+    vcard?: string;
+    contacts?: ContactEntry[];
+    mentionedJids?: string[];
+}
+interface SendLocationInput extends QuoteInput {
+    to: string;
+    latitude: number;
+    longitude: number;
+    name?: string;
+    address?: string;
+}
+/**
+ * Sending is the one place where a retry can be seen by the customer, so every
+ * method takes an idempotency key through `options`. Without it the client
+ * refuses to retry a failed send.
+ */
+declare class MessagesResource {
+    private readonly http;
+    private readonly instanceId;
+    constructor(http: HttpClient, instanceId: string);
+    private get base();
+    sendText(input: SendTextInput, options?: RequestOptions): Promise<SentMessage>;
+    sendMedia(input: SendMediaInput, options?: RequestOptions): Promise<SentMessage>;
+    sendAudio(input: SendAudioInput, options?: RequestOptions): Promise<SentMessage>;
+    sendDocument(input: SendDocumentInput, options?: RequestOptions): Promise<SentMessage>;
+    sendContact(input: SendContactInput, options?: RequestOptions): Promise<SentMessage>;
+    sendLocation(input: SendLocationInput, options?: RequestOptions): Promise<SentMessage>;
+    /** Generic enqueue, for a type the SDK does not model yet. */
+    enqueue(input: {
+        to: string;
+        type: string;
+        payload: string;
+    }, options?: RequestOptions): Promise<SentMessage>;
+    list(options?: RequestOptions): Promise<SentMessage[]>;
+}
+
+interface ApiToken {
+    id: string;
+    name: string;
+    expiresAt?: string;
+    createdAt?: string;
+    /** Only present on creation: the apime never returns it again. */
+    token?: string;
+}
+declare class TokensResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(options?: RequestOptions): Promise<ApiToken[]>;
+    create(input: {
+        name: string;
+        expiresAt?: string;
+    }, options?: RequestOptions): Promise<ApiToken>;
+    delete(tokenId: string, options?: RequestOptions): Promise<void>;
+}
+
+interface User {
+    id: string;
+    email: string;
+    role?: string;
+    createdAt?: string;
+}
+/** Every route here also demands role admin, checked against the database. */
+declare class UsersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(options?: RequestOptions): Promise<User[]>;
+    create(input: {
+        email: string;
+        password: string;
+        role?: string;
+    }, options?: RequestOptions): Promise<User>;
+    updatePassword(userId: string, password: string, options?: RequestOptions): Promise<unknown>;
+    rotateApiToken(userId: string, options?: RequestOptions): Promise<{
+        token: string;
+    }>;
+    delete(userId: string, options?: RequestOptions): Promise<void>;
+}
+
+interface CheckNumberResult {
+    valid?: boolean;
+    jid?: string;
+    [key: string]: unknown;
+}
+interface GroupParticipant {
+    jid: string;
+    isAdmin?: boolean;
+    isSuperAdmin?: boolean;
+}
+interface GroupInfo {
+    jid: string;
+    name?: string;
+    topic?: string;
+    participants?: GroupParticipant[];
+    [key: string]: unknown;
+}
+type PresenceState = "composing" | "paused" | "available" | "unavailable";
+type ParticipantAction = "add" | "remove" | "promote" | "demote";
+type JoinRequestAction = "approve" | "reject";
+/**
+ * Every route here demands the instance token: the apime answers 403 to a user
+ * credential, so this resource only hangs off the instance client.
+ */
+declare class WhatsAppResource {
+    private readonly http;
+    private readonly instanceId;
+    readonly groups: GroupsResource;
+    readonly newsletters: NewslettersResource;
+    constructor(http: HttpClient, instanceId: string);
+    private get base();
+    checkNumber(phone: string, options?: RequestOptions): Promise<CheckNumberResult>;
+    /** `to` is optional: without it the presence is global, not per chat. */
+    setPresence(input: {
+        state: PresenceState;
+        to?: string;
+    }, options?: RequestOptions): Promise<unknown>;
+    listContacts(options?: RequestOptions): Promise<unknown>;
+    getContact(jid: string, options?: RequestOptions): Promise<unknown>;
+    getUserInfo(jid: string, options?: RequestOptions): Promise<unknown>;
+    /** `sender` is required in groups, to identify whose message it is. */
+    markRead(input: {
+        chat: string;
+        message_id: string;
+        sender?: string;
+        played?: boolean;
+    }, options?: RequestOptions): Promise<unknown>;
+    deleteMessage(input: {
+        chat: string;
+        message_id: string;
+        sender?: string;
+    }, options?: RequestOptions): Promise<unknown>;
+    editMessage(input: {
+        chat: string;
+        message_id: string;
+        text: string;
+    }, options?: RequestOptions): Promise<unknown>;
+    /** An empty `emoji` removes the reaction. */
+    react(input: {
+        chat: string;
+        message_id: string;
+        emoji?: string;
+        sender?: string;
+        from_me?: boolean;
+    }, options?: RequestOptions): Promise<unknown>;
+    getPrivacySettings(options?: RequestOptions): Promise<unknown>;
+    setPrivacySetting(input: {
+        name: string;
+        value: string;
+    }, options?: RequestOptions): Promise<unknown>;
+    getStatusPrivacy(options?: RequestOptions): Promise<unknown>;
+    getChatSettings(chat: string, options?: RequestOptions): Promise<unknown>;
+    /** `muted_until` as null unmutes. */
+    setChatSettings(chat: string, input: {
+        muted_until?: string | null;
+        pinned?: boolean;
+        archived?: boolean;
+    }, options?: RequestOptions): Promise<unknown>;
+    setStatusMessage(message: string, options?: RequestOptions): Promise<unknown>;
+    /** `seconds` as 0 turns disappearing messages off. */
+    setDefaultDisappearingTimer(seconds: number, options?: RequestOptions): Promise<unknown>;
+    uploadMedia(input: {
+        media_type: "image" | "video" | "audio" | "document";
+        data_base64: string;
+    }, options?: RequestOptions): Promise<unknown>;
+    /** `revoke` invalidates the previous link and issues another. */
+    getContactQrLink(query?: {
+        revoke?: boolean;
+    }, options?: RequestOptions): Promise<unknown>;
+    resolveContactQrLink(code: string, options?: RequestOptions): Promise<unknown>;
+    resolveBusinessMessageLink(code: string, options?: RequestOptions): Promise<unknown>;
+}
+declare class GroupsResource {
+    private readonly http;
+    private readonly instanceId;
+    constructor(http: HttpClient, instanceId: string);
+    private get base();
+    list(options?: RequestOptions): Promise<GroupInfo[]>;
+    create(input: {
+        name: string;
+        participants?: string[];
+    }, options?: RequestOptions): Promise<GroupInfo>;
+    get(group: string, options?: RequestOptions): Promise<GroupInfo>;
+    getInviteLink(group: string, options?: RequestOptions): Promise<{
+        link?: string;
+    }>;
+    resolveInvite(link: string, options?: RequestOptions): Promise<GroupInfo>;
+    join(link: string, options?: RequestOptions): Promise<unknown>;
+    leave(group: string, options?: RequestOptions): Promise<unknown>;
+    updateParticipants(group: string, input: {
+        action: ParticipantAction;
+        participants: string[];
+    }, options?: RequestOptions): Promise<unknown>;
+    listJoinRequests(group: string, options?: RequestOptions): Promise<unknown>;
+    updateJoinRequests(group: string, input: {
+        action: JoinRequestAction;
+        participants: string[];
+    }, options?: RequestOptions): Promise<unknown>;
+}
+declare class NewslettersResource {
+    private readonly http;
+    private readonly instanceId;
+    constructor(http: HttpClient, instanceId: string);
+    private base;
+    subscribeLiveUpdates(jid: string, options?: RequestOptions): Promise<unknown>;
+    markViewed(jid: string, serverIds: string[], options?: RequestOptions): Promise<unknown>;
+    react(jid: string, input: {
+        server_id: string;
+        reaction?: string;
+        message_id?: string;
+    }, options?: RequestOptions): Promise<unknown>;
+    getMessageUpdates(jid: string, options?: RequestOptions): Promise<unknown>;
+}
+
+interface ClientOptions {
+    baseUrl: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    fetch?: typeof globalThis.fetch;
+    appName?: string;
+    /**
+     * Reports every request, failure and retry to the app's own logger or error
+     * tracker. Nothing is reported without it: the SDK does not pick a vendor.
+     */
+    observer?: Observer;
+    /**
+     * Sem `observer`, a falha definitiva ainda vai para o Sentry que o app já
+     * roda, achado pelo cliente global. Sem Sentry, não faz nada. `false` cala.
+     */
+    autoReport?: boolean;
+}
+interface Credentials {
+    token: string;
+}
+/**
+ * Two clients instead of one, because the apime splits its routes by credential
+ * and a single class would offer methods that always answer 403. Which one you
+ * build decides what the compiler lets you call.
+ */
+declare class ApimeUserClient {
+    readonly instances: InstancesResource;
+    /** Requires the user to have role admin; other users get a 403. */
+    readonly users: UsersResource;
+    readonly tokens: TokensResource;
+    private readonly http;
+    constructor(auth: UserJwtAuth | ApiTokenAuth, options: ClientOptions);
+    /** Escape hatch for a route the SDK does not cover yet. */
+    request<T>(args: Parameters<HttpClient["request"]>[0]): Promise<T>;
+}
+declare class ApimeInstanceClient {
+    readonly instanceId: string;
+    readonly instance: ScopedInstanceResource;
+    readonly messages: MessagesResource;
+    readonly whatsapp: WhatsAppResource;
+    private readonly http;
+    constructor(auth: InstanceTokenAuth, options: ClientOptions);
+    request<T>(args: Parameters<HttpClient["request"]>[0]): Promise<T>;
+}
+/** Entry point. The factory you pick is the credential you have. */
+declare const Apime: {
+    withUserJwt(token: string, options: ClientOptions): ApimeUserClient;
+    withApiToken(token: string, options: ClientOptions): ApimeUserClient;
+    withInstanceToken(credentials: Credentials & {
+        instanceId: string;
+    }, options: ClientOptions): ApimeInstanceClient;
+};
+
+export { type ApiToken, type ApiTokenAuth, Apime, ApimeError, ApimeInstanceClient, ApimeUserClient, type Auth, type AuthKind, type CheckNumberResult, type ClientOptions, type ContactEntry, type CreateInstanceInput, EventLogEntry, type FailureInfo, type GroupInfo, type GroupParticipant, Instance, InstanceInfo, type InstanceTokenAuth, type JoinRequestAction, type MarkReadInput, type Observer, type ParticipantAction, type PresenceState, Profile, QrCode, type QuoteInput, type RequestInfo, type RequestOptions, type SendAudioInput, type SendContactInput, type SendDocumentInput, type SendLocationInput, type SendMediaInput, type SendTextInput, SentMessage, type SuccessInfo, type UpdateInstanceInput, type User, type UserAuth, type UserJwtAuth, hasSentry };