@open-apime/sdk 0.2.2

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,44 @@
+# @open-apime/sdk
+
+Cliente TypeScript da API do [apime](https://github.com/open-apime/apime): envio de WhatsApp,
+gestão de instâncias e verificação de webhook.
+
+```bash
+npm install @open-apime/sdk
+```
+
+```ts
+import { Apime } from "@open-apime/sdk";
+
+const conexao = Apime.withInstanceToken(
+  { token: process.env.INSTANCE_TOKEN!, instanceId: "abc-123" },
+  { baseUrl: "https://apime.example.com" },
+);
+
+await conexao.messages.sendText(
+  { to: "5511999999999", text: "Olá" },
+  { idempotencyKey: mensagem.id },
+);
+```
+
+- **Zero dependência de runtime.** `fetch` e `crypto` do próprio Node (18+).
+- **Tipado por token:** o cliente que você constrói define o que compila, então token errado para a
+  rota vira erro de compilação, não `403` em produção.
+- **Retry seguro:** leitura retenta sozinha, envio só com `Idempotency-Key`.
+- **Webhook verificado** em tempo constante, sobre o corpo cru.
+- Cobre as **66 operações** do contrato do apime.
+
+## Documentação
+
+| | |
+|---|---|
+| [Guia de uso](https://github.com/open-apime/sdk/blob/main/docs/guia.md) | clientes, envio, erros, retry, observabilidade e webhook |
+| [Segurança](https://github.com/open-apime/sdk/blob/main/docs/seguranca.md) | o que o SDK protege, e como |
+| [openapi.yaml](https://github.com/open-apime/apime/blob/main/openapi.yaml) | contrato da API |
+| [webhook-payloads.md](https://github.com/open-apime/apime/blob/main/docs/webhook-payloads.md) | os 12 eventos |
+
+Enquanto está em `0.x`, minor pode trazer mudança incompatível.
+
+## Licença
+
+MIT.

package/dist/chunk-HS2RZ6SJ.js

@@ -0,0 +1,93 @@
+// src/webhook/index.ts
+import { createHmac, timingSafeEqual } from "crypto";
+
+// src/errors/index.ts
+var ApimeError = class extends Error {
+  status;
+  body;
+  /** Value of the request id header, when the response carried one. */
+  requestId;
+  constructor(message, options = {}) {
+    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.name = new.target.name;
+    this.status = options.status;
+    this.body = options.body;
+    this.requestId = options.requestId;
+  }
+};
+var AuthenticationError = class extends ApimeError {
+};
+var PermissionError = class extends ApimeError {
+};
+var NotFoundError = class extends ApimeError {
+};
+var ConflictError = class extends ApimeError {
+};
+var UnprocessableError = class extends ApimeError {
+};
+var RateLimitError = class extends ApimeError {
+  retryAfterMs;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.retryAfterMs = options.retryAfterMs;
+  }
+};
+var InvalidRequestError = class extends ApimeError {
+};
+var ApiError = class extends ApimeError {
+};
+var SessionUnavailableError = class extends ApiError {
+};
+var ConnectionError = class extends ApimeError {
+};
+var TimeoutError = class extends ConnectionError {
+};
+var ConfigurationError = class extends ApimeError {
+};
+
+// src/webhook/index.ts
+var SIGNATURE_HEADER = "X-ApiMe-Signature";
+var InvalidSignatureError = class extends ApimeError {
+};
+function verifyWebhookSignature(rawBody, signature, secret) {
+  if (!signature || !secret) return false;
+  const body = typeof rawBody === "string" ? Buffer.from(rawBody, "utf8") : rawBody;
+  const expected = `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`;
+  const received = Buffer.from(signature, "utf8");
+  const digest = Buffer.from(expected, "utf8");
+  if (received.length !== digest.length) return false;
+  return timingSafeEqual(received, digest);
+}
+function constructEvent(rawBody, signature, secret) {
+  if (!verifyWebhookSignature(rawBody, signature, secret)) {
+    throw new InvalidSignatureError("assinatura do webhook n\xE3o confere");
+  }
+  const text = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (cause) {
+    throw new InvalidSignatureError("corpo do webhook n\xE3o \xE9 JSON v\xE1lido", { cause });
+  }
+  return parsed;
+}
+
+export {
+  ApimeError,
+  AuthenticationError,
+  PermissionError,
+  NotFoundError,
+  ConflictError,
+  UnprocessableError,
+  RateLimitError,
+  InvalidRequestError,
+  ApiError,
+  SessionUnavailableError,
+  ConnectionError,
+  TimeoutError,
+  ConfigurationError,
+  SIGNATURE_HEADER,
+  InvalidSignatureError,
+  verifyWebhookSignature,
+  constructEvent
+};

package/dist/events-BV5UVoFu.d.cts

@@ -0,0 +1,90 @@
+/**
+ * The 12 event types the apime delivers. `ignore` is internal and never
+ * reaches a consumer, so it is not part of the union.
+ */
+type WebhookEventType = "message" | "receipt" | "presence" | "chat_presence" | "reaction" | "contact_update" | "connected" | "disconnected" | "temporary_ban" | "restriction_lifted" | "contact_reachout_locked" | "unknown";
+interface WebhookEnvelope<T extends WebhookEventType = WebhookEventType, P = unknown> {
+    id: string;
+    instanceId: string;
+    type: T;
+    payload: P;
+    createdAt: string;
+}
+/** Button of an interactive message. `call`, `copy`, `reply` and `url` are button kinds, not events. */
+interface MessageButton {
+    id: string;
+    label: string;
+    type: "reply" | "url" | "copy" | "call";
+    url?: string;
+    code?: string;
+    phone?: string;
+}
+interface MessagePayload {
+    from: string;
+    to: string;
+    isFromMe: boolean;
+    isGroup: boolean;
+    messageId: string;
+    timestamp: number;
+    pushName?: string;
+    text?: string;
+    mediaType?: "image" | "video" | "audio" | "document" | "sticker" | "location" | "contact";
+    mediaUrl?: string;
+    mimetype?: string;
+    caption?: string;
+    buttons?: MessageButton[];
+    /**
+     * Present only when this event is an edit: the id of the message that was
+     * edited, and its new text. They always travel together, so checking one is
+     * enough to know it is an edit.
+     */
+    editedMessageId?: string;
+    editedText?: string;
+}
+interface ReceiptPayload {
+    messageIds: string[];
+    timestamp: number;
+    chat: string;
+    status: "read" | "delivered" | "played";
+}
+interface PresencePayload {
+    from: string;
+    unavailable: boolean;
+    lastSeen?: number;
+}
+interface ChatPresencePayload {
+    from: string;
+    chatJID: string;
+    state: "composing" | "paused";
+    media?: "audio";
+}
+interface ContactUpdatePayload {
+    jid: string;
+    username: string;
+}
+interface DisconnectedPayload {
+    reason?: string;
+}
+/** Same shape for the account ban and for the reach-out timelock. */
+interface TemporaryBanPayload {
+    reason?: string;
+    code?: number;
+    active: boolean;
+    restrictedUntil?: string;
+    enforcementType?: string;
+}
+interface RestrictionLiftedPayload {
+    active: false;
+    enforcementType?: string;
+    restrictedUntil?: string;
+}
+interface ContactReachoutLockedPayload {
+    to: string;
+    reason: string;
+    detail: string;
+    code: number;
+}
+/** Discriminated by `type`, so a switch narrows the payload. */
+type WebhookEvent = WebhookEnvelope<"message", MessagePayload> | WebhookEnvelope<"receipt", ReceiptPayload> | WebhookEnvelope<"presence", PresencePayload> | WebhookEnvelope<"chat_presence", ChatPresencePayload> | WebhookEnvelope<"reaction", Record<string, unknown>> | WebhookEnvelope<"contact_update", ContactUpdatePayload> | WebhookEnvelope<"connected", Record<string, unknown>> | WebhookEnvelope<"disconnected", DisconnectedPayload> | WebhookEnvelope<"temporary_ban", TemporaryBanPayload> | WebhookEnvelope<"restriction_lifted", RestrictionLiftedPayload> | WebhookEnvelope<"contact_reachout_locked", ContactReachoutLockedPayload> | WebhookEnvelope<"unknown", Record<string, unknown>>;
+
+export type { ChatPresencePayload as C, DisconnectedPayload as D, MessageButton as M, PresencePayload as P, ReceiptPayload as R, TemporaryBanPayload as T, WebhookEnvelope as W, ContactReachoutLockedPayload as a, ContactUpdatePayload as b, MessagePayload as c, RestrictionLiftedPayload as d, WebhookEvent as e, WebhookEventType as f };

package/dist/events-BV5UVoFu.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The 12 event types the apime delivers. `ignore` is internal and never
+ * reaches a consumer, so it is not part of the union.
+ */
+type WebhookEventType = "message" | "receipt" | "presence" | "chat_presence" | "reaction" | "contact_update" | "connected" | "disconnected" | "temporary_ban" | "restriction_lifted" | "contact_reachout_locked" | "unknown";
+interface WebhookEnvelope<T extends WebhookEventType = WebhookEventType, P = unknown> {
+    id: string;
+    instanceId: string;
+    type: T;
+    payload: P;
+    createdAt: string;
+}
+/** Button of an interactive message. `call`, `copy`, `reply` and `url` are button kinds, not events. */
+interface MessageButton {
+    id: string;
+    label: string;
+    type: "reply" | "url" | "copy" | "call";
+    url?: string;
+    code?: string;
+    phone?: string;
+}
+interface MessagePayload {
+    from: string;
+    to: string;
+    isFromMe: boolean;
+    isGroup: boolean;
+    messageId: string;
+    timestamp: number;
+    pushName?: string;
+    text?: string;
+    mediaType?: "image" | "video" | "audio" | "document" | "sticker" | "location" | "contact";
+    mediaUrl?: string;
+    mimetype?: string;
+    caption?: string;
+    buttons?: MessageButton[];
+    /**
+     * Present only when this event is an edit: the id of the message that was
+     * edited, and its new text. They always travel together, so checking one is
+     * enough to know it is an edit.
+     */
+    editedMessageId?: string;
+    editedText?: string;
+}
+interface ReceiptPayload {
+    messageIds: string[];
+    timestamp: number;
+    chat: string;
+    status: "read" | "delivered" | "played";
+}
+interface PresencePayload {
+    from: string;
+    unavailable: boolean;
+    lastSeen?: number;
+}
+interface ChatPresencePayload {
+    from: string;
+    chatJID: string;
+    state: "composing" | "paused";
+    media?: "audio";
+}
+interface ContactUpdatePayload {
+    jid: string;
+    username: string;
+}
+interface DisconnectedPayload {
+    reason?: string;
+}
+/** Same shape for the account ban and for the reach-out timelock. */
+interface TemporaryBanPayload {
+    reason?: string;
+    code?: number;
+    active: boolean;
+    restrictedUntil?: string;
+    enforcementType?: string;
+}
+interface RestrictionLiftedPayload {
+    active: false;
+    enforcementType?: string;
+    restrictedUntil?: string;
+}
+interface ContactReachoutLockedPayload {
+    to: string;
+    reason: string;
+    detail: string;
+    code: number;
+}
+/** Discriminated by `type`, so a switch narrows the payload. */
+type WebhookEvent = WebhookEnvelope<"message", MessagePayload> | WebhookEnvelope<"receipt", ReceiptPayload> | WebhookEnvelope<"presence", PresencePayload> | WebhookEnvelope<"chat_presence", ChatPresencePayload> | WebhookEnvelope<"reaction", Record<string, unknown>> | WebhookEnvelope<"contact_update", ContactUpdatePayload> | WebhookEnvelope<"connected", Record<string, unknown>> | WebhookEnvelope<"disconnected", DisconnectedPayload> | WebhookEnvelope<"temporary_ban", TemporaryBanPayload> | WebhookEnvelope<"restriction_lifted", RestrictionLiftedPayload> | WebhookEnvelope<"contact_reachout_locked", ContactReachoutLockedPayload> | WebhookEnvelope<"unknown", Record<string, unknown>>;
+
+export type { ChatPresencePayload as C, DisconnectedPayload as D, MessageButton as M, PresencePayload as P, ReceiptPayload as R, TemporaryBanPayload as T, WebhookEnvelope as W, ContactReachoutLockedPayload as a, ContactUpdatePayload as b, MessagePayload as c, RestrictionLiftedPayload as d, WebhookEvent as e, WebhookEventType as f };

package/dist/index-37ITjlwO.d.cts

@@ -0,0 +1,83 @@
+import { e as WebhookEvent } from './events-BV5UVoFu.cjs';
+
+/**
+ * One class per condition, so callers branch on the error instead of parsing
+ * status codes. Mirrors what the apime returns.
+ */
+declare class ApimeError extends Error {
+    readonly status: number | undefined;
+    readonly body: unknown;
+    /** Value of the request id header, when the response carried one. */
+    readonly requestId: string | undefined;
+    constructor(message: string, options?: {
+        status?: number;
+        body?: unknown;
+        requestId?: string;
+        cause?: unknown;
+    });
+}
+/** 401: token missing, malformed or unknown. */
+declare class AuthenticationError extends ApimeError {
+}
+/**
+ * 403: the token is valid but not for this. Most often an instance route
+ * reached with a user token, or a token from another instance.
+ */
+declare class PermissionError extends ApimeError {
+}
+/** 404. */
+declare class NotFoundError extends ApimeError {
+}
+/** 409: another request with the same Idempotency-Key is still running. */
+declare class ConflictError extends ApimeError {
+}
+/** 422: rejected payload, or an Idempotency-Key reused with different content. */
+declare class UnprocessableError extends ApimeError {
+}
+/** 429: rate limited. `retryAfterMs` comes from the Retry-After header. */
+declare class RateLimitError extends ApimeError {
+    readonly retryAfterMs: number | undefined;
+    constructor(message: string, options?: {
+        status?: number;
+        body?: unknown;
+        requestId?: string;
+        retryAfterMs?: number;
+    });
+}
+/** 400 and other client-side rejections. */
+declare class InvalidRequestError extends ApimeError {
+}
+/** 5xx. */
+declare class ApiError extends ApimeError {
+}
+/**
+ * 503: the instance session is not ready. Nothing was sent, so this is safe to
+ * retry, including with the same Idempotency-Key.
+ */
+declare class SessionUnavailableError extends ApiError {
+}
+/** The request never got an answer: DNS, refused connection, socket reset. */
+declare class ConnectionError extends ApimeError {
+}
+/** The request was aborted by the configured timeout. */
+declare class TimeoutError extends ConnectionError {
+}
+/** Raised before any request when the configured base URL is unusable. */
+declare class ConfigurationError extends ApimeError {
+}
+
+declare const SIGNATURE_HEADER = "X-ApiMe-Signature";
+declare class InvalidSignatureError extends ApimeError {
+}
+/**
+ * Verifies against the raw body, never a re-serialized object: JSON.stringify
+ * of a parsed payload reorders keys and the HMAC stops matching.
+ */
+declare function verifyWebhookSignature(rawBody: string | Buffer, signature: string | undefined, secret: string): boolean;
+/**
+ * Checks the signature and returns the typed event, or throws. Same shape as
+ * the Stripe helper, so the raw-body requirement is the only thing to remember.
+ */
+declare function constructEvent(rawBody: string | Buffer, signature: string | undefined, secret: string): WebhookEvent;
+
+export { ApimeError as A, ConfigurationError as C, InvalidRequestError as I, NotFoundError as N, PermissionError as P, RateLimitError as R, SessionUnavailableError as S, TimeoutError as T, UnprocessableError as U, ApiError as a, AuthenticationError as b, ConflictError as c, ConnectionError as d, InvalidSignatureError as e, constructEvent as f, SIGNATURE_HEADER as g, verifyWebhookSignature as v };

package/dist/index-TqYrYke0.d.ts

@@ -0,0 +1,83 @@
+import { e as WebhookEvent } from './events-BV5UVoFu.js';
+
+/**
+ * One class per condition, so callers branch on the error instead of parsing
+ * status codes. Mirrors what the apime returns.
+ */
+declare class ApimeError extends Error {
+    readonly status: number | undefined;
+    readonly body: unknown;
+    /** Value of the request id header, when the response carried one. */
+    readonly requestId: string | undefined;
+    constructor(message: string, options?: {
+        status?: number;
+        body?: unknown;
+        requestId?: string;
+        cause?: unknown;
+    });
+}
+/** 401: token missing, malformed or unknown. */
+declare class AuthenticationError extends ApimeError {
+}
+/**
+ * 403: the token is valid but not for this. Most often an instance route
+ * reached with a user token, or a token from another instance.
+ */
+declare class PermissionError extends ApimeError {
+}
+/** 404. */
+declare class NotFoundError extends ApimeError {
+}
+/** 409: another request with the same Idempotency-Key is still running. */
+declare class ConflictError extends ApimeError {
+}
+/** 422: rejected payload, or an Idempotency-Key reused with different content. */
+declare class UnprocessableError extends ApimeError {
+}
+/** 429: rate limited. `retryAfterMs` comes from the Retry-After header. */
+declare class RateLimitError extends ApimeError {
+    readonly retryAfterMs: number | undefined;
+    constructor(message: string, options?: {
+        status?: number;
+        body?: unknown;
+        requestId?: string;
+        retryAfterMs?: number;
+    });
+}
+/** 400 and other client-side rejections. */
+declare class InvalidRequestError extends ApimeError {
+}
+/** 5xx. */
+declare class ApiError extends ApimeError {
+}
+/**
+ * 503: the instance session is not ready. Nothing was sent, so this is safe to
+ * retry, including with the same Idempotency-Key.
+ */
+declare class SessionUnavailableError extends ApiError {
+}
+/** The request never got an answer: DNS, refused connection, socket reset. */
+declare class ConnectionError extends ApimeError {
+}
+/** The request was aborted by the configured timeout. */
+declare class TimeoutError extends ConnectionError {
+}
+/** Raised before any request when the configured base URL is unusable. */
+declare class ConfigurationError extends ApimeError {
+}
+
+declare const SIGNATURE_HEADER = "X-ApiMe-Signature";
+declare class InvalidSignatureError extends ApimeError {
+}
+/**
+ * Verifies against the raw body, never a re-serialized object: JSON.stringify
+ * of a parsed payload reorders keys and the HMAC stops matching.
+ */
+declare function verifyWebhookSignature(rawBody: string | Buffer, signature: string | undefined, secret: string): boolean;
+/**
+ * Checks the signature and returns the typed event, or throws. Same shape as
+ * the Stripe helper, so the raw-body requirement is the only thing to remember.
+ */
+declare function constructEvent(rawBody: string | Buffer, signature: string | undefined, secret: string): WebhookEvent;
+
+export { ApimeError as A, ConfigurationError as C, InvalidRequestError as I, NotFoundError as N, PermissionError as P, RateLimitError as R, SessionUnavailableError as S, TimeoutError as T, UnprocessableError as U, ApiError as a, AuthenticationError as b, ConflictError as c, ConnectionError as d, InvalidSignatureError as e, constructEvent as f, SIGNATURE_HEADER as g, verifyWebhookSignature as v };