@reachflow/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,238 @@
+/** Statut de cycle de vie d'un message API. */
+type MessageStatus = 'queued' | 'processing' | 'sent' | 'delivered' | 'failed' | 'cancelled';
+type MediaType = 'image' | 'document' | 'audio' | 'video';
+type FailureCode = 'warmup_daily_limit' | 'risk_circuit_open' | 'provider_disconnected' | 'provider_banned' | 'send_not_allowed' | 'instance_busy' | 'delivery_timeout' | 'delivery_failed' | 'send_error' | 'provider_not_found';
+type OtpVerifyReason = 'invalidated' | 'already_used' | 'expired' | 'max_attempts_reached' | 'invalid_code' | 'not_found';
+interface ReachFlowClientOptions {
+    /** Clé API `rfl_live_…` ou `rfl_test_…`. */
+    apiKey: string;
+    /**
+     * URL de base sans `/api/v1` (défaut : sandbox ReachFlow).
+     * @default "https://sandbox-api.reachflow.me"
+     */
+    baseUrl?: string;
+    /** Timeout HTTP en millisecondes. @default 30000 */
+    timeoutMs?: number;
+    /** Implémentation fetch (tests, Node < 18). @default global fetch */
+    fetch?: typeof fetch;
+    /** Nombre max de retries sur 429 / 5xx retryables. @default 2 */
+    maxRetries?: number;
+}
+interface SendMessageParams {
+    providerId: string;
+    to: string;
+    message: string;
+    variables?: Record<string, string>;
+    scheduleAt?: string;
+    saveContact?: boolean;
+    idempotencyKey?: string;
+}
+interface SendMediaParams {
+    providerId: string;
+    to: string;
+    mediaUrl: string;
+    mediaType: MediaType;
+    caption?: string;
+    saveContact?: boolean;
+    idempotencyKey?: string;
+}
+interface BulkRecipient {
+    to: string;
+    variables?: Record<string, string>;
+}
+interface SendBulkParams {
+    providerId: string;
+    messageTemplate: string;
+    recipients: BulkRecipient[];
+    scheduleAt?: string;
+    saveContact?: boolean;
+    idempotencyKey?: string;
+}
+interface SendAcceptedResponse {
+    messageId: string;
+    status: 'queued';
+    queuedAt: string;
+}
+interface BulkRejection {
+    to: string;
+    reason: string;
+}
+interface SendBulkResponse {
+    bulkId: string;
+    accepted: number;
+    rejected: number;
+    rejections: BulkRejection[];
+    messageIds: string[];
+}
+interface MessageStatusResponse {
+    messageId: string;
+    status: MessageStatus;
+    to: string;
+    providerId: string;
+    queuedAt: string;
+    sentAt: string | null;
+    deliveredAt: string | null;
+    failedAt: string | null;
+    failureCode: FailureCode | null;
+    failureReason: string | null;
+}
+interface ProviderSummary {
+    id: string;
+    name: string;
+    phoneNumber: string | null;
+    status: string;
+    warmupDay: number;
+    riskScore: number;
+}
+interface ProviderDailyStats {
+    sent: number;
+    delivered: number;
+    failed: number;
+    messagesLimit: number | null;
+    newContactsLimit: number | null;
+}
+interface ProviderDetail extends ProviderSummary {
+    dailyStats: ProviderDailyStats;
+}
+interface ProviderListResponse {
+    providers: ProviderSummary[];
+}
+interface OtpSendParams {
+    providerId: string;
+    phoneNumber: string;
+    codeLength?: number;
+    expiresIn?: number;
+    brandName?: string;
+    template?: string;
+    saveContact?: boolean;
+}
+interface OtpSendResponse {
+    otpId: string;
+    messageId: string;
+    expiresAt: string;
+}
+interface OtpVerifyParams {
+    otpId: string;
+    code: string;
+}
+interface OtpVerifyResponse {
+    valid: boolean;
+    reason?: OtpVerifyReason;
+    attemptsLeft?: number;
+}
+interface WaitForTerminalOptions {
+    /** Intervalle entre polls en ms. @default 2000 */
+    pollIntervalMs?: number;
+    /** Timeout total en ms. @default 120000 */
+    timeoutMs?: number;
+}
+declare const TERMINAL_MESSAGE_STATUSES: ReadonlySet<MessageStatus>;
+declare const DEFAULT_BASE_URL = "https://sandbox-api.reachflow.me";
+
+interface RequestOptions {
+    method: 'GET' | 'POST';
+    path: string;
+    body?: unknown;
+    idempotencyKey?: string;
+}
+interface ResolvedClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    apiPrefix: string;
+    timeoutMs: number;
+    fetchImpl: typeof fetch;
+    maxRetries: number;
+}
+declare class HttpClient {
+    private readonly config;
+    constructor(config: ResolvedClientConfig);
+    request<T>(options: RequestOptions): Promise<T>;
+    private requestOnce;
+}
+
+declare class MessagesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Envoie un message texte (réponse HTTP 202). */
+    send(params: SendMessageParams): Promise<SendAcceptedResponse>;
+    /** Envoie un média via URL HTTPS publique (réponse HTTP 202). */
+    sendMedia(params: SendMediaParams): Promise<SendAcceptedResponse>;
+    /** Envoie un lot de messages (même modèle, destinataires multiples). */
+    sendBulk(params: SendBulkParams): Promise<SendBulkResponse>;
+    /** Consulte le statut d'un message précédemment accepté. */
+    getStatus(messageId: string): Promise<MessageStatusResponse>;
+    /**
+     * Poll jusqu'à un statut terminal (`sent`, `delivered`, `failed`, `cancelled`).
+     * Lance `ReachFlowError` si timeout.
+     */
+    waitForTerminal(messageId: string, options?: WaitForTerminalOptions): Promise<MessageStatusResponse>;
+}
+
+declare class OtpResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Génère et envoie un code OTP par WhatsApp.
+     * Le code n'est jamais retourné par l'API — uniquement sur WhatsApp.
+     */
+    send(params: OtpSendParams): Promise<OtpSendResponse>;
+    /** Vérifie un code saisi par l'utilisateur final. */
+    verify(params: OtpVerifyParams): Promise<OtpVerifyResponse>;
+}
+
+declare class ProvidersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Liste les numéros WhatsApp accessibles via l'API. */
+    list(): Promise<ProviderListResponse>;
+    /** Détail d'un provider avec statistiques journalières. */
+    get(providerId: string): Promise<ProviderDetail>;
+    /**
+     * Retourne le premier provider au statut `connected`, ou le premier de la liste.
+     * Utile pour les scripts de test / démarrage rapide.
+     */
+    findConnected(): Promise<ProviderDetail | ProviderListResponse['providers'][number] | null>;
+}
+
+/**
+ * Client officiel pour l'API publique ReachFlow (REST v1).
+ *
+ * @example
+ * ```ts
+ * const client = new ReachFlow({ apiKey: process.env.REACHFLOW_API_KEY! });
+ * const { providers } = await client.providers.list();
+ * ```
+ */
+declare class ReachFlow {
+    readonly messages: MessagesResource;
+    readonly providers: ProvidersResource;
+    readonly otp: OtpResource;
+    private readonly http;
+    private readonly config;
+    constructor(options: ReachFlowClientOptions);
+    /** URL de base configurée (sans `/api/v1`). */
+    get baseUrl(): string;
+}
+
+type ReachFlowErrorCode = 'unauthorized' | 'plan_required' | 'insufficient_scope' | 'rate_limit_exceeded' | 'too_many_auth_failures' | 'validation_error' | 'not_found' | 'api_error' | 'network_error' | 'timeout';
+declare class ReachFlowError extends Error {
+    readonly statusCode: number;
+    readonly code: ReachFlowErrorCode;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+    readonly body?: unknown;
+    constructor(params: {
+        message: string;
+        statusCode: number;
+        code: ReachFlowErrorCode;
+        retryable?: boolean;
+        retryAfterMs?: number;
+        body?: unknown;
+        cause?: unknown;
+    });
+    static fromResponse(status: number, body: unknown, fallbackMessage?: string): ReachFlowError;
+    static network(cause: unknown): ReachFlowError;
+    static timeout(timeoutMs: number): ReachFlowError;
+}
+
+export { type BulkRecipient, DEFAULT_BASE_URL, type FailureCode, type MediaType, type MessageStatus, type MessageStatusResponse, type OtpSendParams, type OtpSendResponse, type OtpVerifyParams, type OtpVerifyReason, type OtpVerifyResponse, type ProviderDailyStats, type ProviderDetail, type ProviderListResponse, type ProviderSummary, ReachFlow, type ReachFlowClientOptions, ReachFlowError, type ReachFlowErrorCode, type SendAcceptedResponse, type SendBulkParams, type SendBulkResponse, type SendMediaParams, type SendMessageParams, TERMINAL_MESSAGE_STATUSES, type WaitForTerminalOptions };

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+/** Statut de cycle de vie d'un message API. */
+type MessageStatus = 'queued' | 'processing' | 'sent' | 'delivered' | 'failed' | 'cancelled';
+type MediaType = 'image' | 'document' | 'audio' | 'video';
+type FailureCode = 'warmup_daily_limit' | 'risk_circuit_open' | 'provider_disconnected' | 'provider_banned' | 'send_not_allowed' | 'instance_busy' | 'delivery_timeout' | 'delivery_failed' | 'send_error' | 'provider_not_found';
+type OtpVerifyReason = 'invalidated' | 'already_used' | 'expired' | 'max_attempts_reached' | 'invalid_code' | 'not_found';
+interface ReachFlowClientOptions {
+    /** Clé API `rfl_live_…` ou `rfl_test_…`. */
+    apiKey: string;
+    /**
+     * URL de base sans `/api/v1` (défaut : sandbox ReachFlow).
+     * @default "https://sandbox-api.reachflow.me"
+     */
+    baseUrl?: string;
+    /** Timeout HTTP en millisecondes. @default 30000 */
+    timeoutMs?: number;
+    /** Implémentation fetch (tests, Node < 18). @default global fetch */
+    fetch?: typeof fetch;
+    /** Nombre max de retries sur 429 / 5xx retryables. @default 2 */
+    maxRetries?: number;
+}
+interface SendMessageParams {
+    providerId: string;
+    to: string;
+    message: string;
+    variables?: Record<string, string>;
+    scheduleAt?: string;
+    saveContact?: boolean;
+    idempotencyKey?: string;
+}
+interface SendMediaParams {
+    providerId: string;
+    to: string;
+    mediaUrl: string;
+    mediaType: MediaType;
+    caption?: string;
+    saveContact?: boolean;
+    idempotencyKey?: string;
+}
+interface BulkRecipient {
+    to: string;
+    variables?: Record<string, string>;
+}
+interface SendBulkParams {
+    providerId: string;
+    messageTemplate: string;
+    recipients: BulkRecipient[];
+    scheduleAt?: string;
+    saveContact?: boolean;
+    idempotencyKey?: string;
+}
+interface SendAcceptedResponse {
+    messageId: string;
+    status: 'queued';
+    queuedAt: string;
+}
+interface BulkRejection {
+    to: string;
+    reason: string;
+}
+interface SendBulkResponse {
+    bulkId: string;
+    accepted: number;
+    rejected: number;
+    rejections: BulkRejection[];
+    messageIds: string[];
+}
+interface MessageStatusResponse {
+    messageId: string;
+    status: MessageStatus;
+    to: string;
+    providerId: string;
+    queuedAt: string;
+    sentAt: string | null;
+    deliveredAt: string | null;
+    failedAt: string | null;
+    failureCode: FailureCode | null;
+    failureReason: string | null;
+}
+interface ProviderSummary {
+    id: string;
+    name: string;
+    phoneNumber: string | null;
+    status: string;
+    warmupDay: number;
+    riskScore: number;
+}
+interface ProviderDailyStats {
+    sent: number;
+    delivered: number;
+    failed: number;
+    messagesLimit: number | null;
+    newContactsLimit: number | null;
+}
+interface ProviderDetail extends ProviderSummary {
+    dailyStats: ProviderDailyStats;
+}
+interface ProviderListResponse {
+    providers: ProviderSummary[];
+}
+interface OtpSendParams {
+    providerId: string;
+    phoneNumber: string;
+    codeLength?: number;
+    expiresIn?: number;
+    brandName?: string;
+    template?: string;
+    saveContact?: boolean;
+}
+interface OtpSendResponse {
+    otpId: string;
+    messageId: string;
+    expiresAt: string;
+}
+interface OtpVerifyParams {
+    otpId: string;
+    code: string;
+}
+interface OtpVerifyResponse {
+    valid: boolean;
+    reason?: OtpVerifyReason;
+    attemptsLeft?: number;
+}
+interface WaitForTerminalOptions {
+    /** Intervalle entre polls en ms. @default 2000 */
+    pollIntervalMs?: number;
+    /** Timeout total en ms. @default 120000 */
+    timeoutMs?: number;
+}
+declare const TERMINAL_MESSAGE_STATUSES: ReadonlySet<MessageStatus>;
+declare const DEFAULT_BASE_URL = "https://sandbox-api.reachflow.me";
+
+interface RequestOptions {
+    method: 'GET' | 'POST';
+    path: string;
+    body?: unknown;
+    idempotencyKey?: string;
+}
+interface ResolvedClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    apiPrefix: string;
+    timeoutMs: number;
+    fetchImpl: typeof fetch;
+    maxRetries: number;
+}
+declare class HttpClient {
+    private readonly config;
+    constructor(config: ResolvedClientConfig);
+    request<T>(options: RequestOptions): Promise<T>;
+    private requestOnce;
+}
+
+declare class MessagesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Envoie un message texte (réponse HTTP 202). */
+    send(params: SendMessageParams): Promise<SendAcceptedResponse>;
+    /** Envoie un média via URL HTTPS publique (réponse HTTP 202). */
+    sendMedia(params: SendMediaParams): Promise<SendAcceptedResponse>;
+    /** Envoie un lot de messages (même modèle, destinataires multiples). */
+    sendBulk(params: SendBulkParams): Promise<SendBulkResponse>;
+    /** Consulte le statut d'un message précédemment accepté. */
+    getStatus(messageId: string): Promise<MessageStatusResponse>;
+    /**
+     * Poll jusqu'à un statut terminal (`sent`, `delivered`, `failed`, `cancelled`).
+     * Lance `ReachFlowError` si timeout.
+     */
+    waitForTerminal(messageId: string, options?: WaitForTerminalOptions): Promise<MessageStatusResponse>;
+}
+
+declare class OtpResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Génère et envoie un code OTP par WhatsApp.
+     * Le code n'est jamais retourné par l'API — uniquement sur WhatsApp.
+     */
+    send(params: OtpSendParams): Promise<OtpSendResponse>;
+    /** Vérifie un code saisi par l'utilisateur final. */
+    verify(params: OtpVerifyParams): Promise<OtpVerifyResponse>;
+}
+
+declare class ProvidersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Liste les numéros WhatsApp accessibles via l'API. */
+    list(): Promise<ProviderListResponse>;
+    /** Détail d'un provider avec statistiques journalières. */
+    get(providerId: string): Promise<ProviderDetail>;
+    /**
+     * Retourne le premier provider au statut `connected`, ou le premier de la liste.
+     * Utile pour les scripts de test / démarrage rapide.
+     */
+    findConnected(): Promise<ProviderDetail | ProviderListResponse['providers'][number] | null>;
+}
+
+/**
+ * Client officiel pour l'API publique ReachFlow (REST v1).
+ *
+ * @example
+ * ```ts
+ * const client = new ReachFlow({ apiKey: process.env.REACHFLOW_API_KEY! });
+ * const { providers } = await client.providers.list();
+ * ```
+ */
+declare class ReachFlow {
+    readonly messages: MessagesResource;
+    readonly providers: ProvidersResource;
+    readonly otp: OtpResource;
+    private readonly http;
+    private readonly config;
+    constructor(options: ReachFlowClientOptions);
+    /** URL de base configurée (sans `/api/v1`). */
+    get baseUrl(): string;
+}
+
+type ReachFlowErrorCode = 'unauthorized' | 'plan_required' | 'insufficient_scope' | 'rate_limit_exceeded' | 'too_many_auth_failures' | 'validation_error' | 'not_found' | 'api_error' | 'network_error' | 'timeout';
+declare class ReachFlowError extends Error {
+    readonly statusCode: number;
+    readonly code: ReachFlowErrorCode;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+    readonly body?: unknown;
+    constructor(params: {
+        message: string;
+        statusCode: number;
+        code: ReachFlowErrorCode;
+        retryable?: boolean;
+        retryAfterMs?: number;
+        body?: unknown;
+        cause?: unknown;
+    });
+    static fromResponse(status: number, body: unknown, fallbackMessage?: string): ReachFlowError;
+    static network(cause: unknown): ReachFlowError;
+    static timeout(timeoutMs: number): ReachFlowError;
+}
+
+export { type BulkRecipient, DEFAULT_BASE_URL, type FailureCode, type MediaType, type MessageStatus, type MessageStatusResponse, type OtpSendParams, type OtpSendResponse, type OtpVerifyParams, type OtpVerifyReason, type OtpVerifyResponse, type ProviderDailyStats, type ProviderDetail, type ProviderListResponse, type ProviderSummary, ReachFlow, type ReachFlowClientOptions, ReachFlowError, type ReachFlowErrorCode, type SendAcceptedResponse, type SendBulkParams, type SendBulkResponse, type SendMediaParams, type SendMessageParams, TERMINAL_MESSAGE_STATUSES, type WaitForTerminalOptions };