@fastermessage/sdk 0.0.0-stage → 0.1.2

package/dist/esm/http.d.ts

@@ -0,0 +1,30 @@
+export declare const VERSION = "0.1.2";
+export interface RequestOptions {
+    /** Votre clé, pour survivre à un redémarrage de votre programme. */
+    idempotencyKey?: string;
+    /** Repris par `X-Request-Id`, pour relier l'appel à vos journaux. */
+    requestId?: string;
+    /** Annule l'appel. Une annulation n'est jamais rejouée. */
+    signal?: AbortSignal;
+}
+export interface RequesterConfig {
+    authorization: string;
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+    maxRetries: number;
+    fetch?: typeof globalThis.fetch;
+    sleep?: (milliseconds: number) => Promise<void>;
+}
+interface Call {
+    query?: object;
+    body?: object;
+    options?: RequestOptions | undefined;
+}
+/** Le chemin unique de tous les appels : en-têtes, idempotence, reprises, erreurs. */
+export declare class Requester {
+    #private;
+    constructor(config: RequesterConfig);
+    request<T>(method: string, path: string, { query, body, options }?: Call): Promise<T>;
+}
+export {};

package/dist/esm/http.js

@@ -0,0 +1,166 @@
+import { randomBytes } from 'node:crypto';
+import { ApiError, AuthenticationError, ConflictError, ConnectionError, InsufficientBalanceError, InvalidRequestError, NotFoundError, NotImplementedError, PermissionError, RateLimitError, ServerError, } from './errors.js';
+export const VERSION = '0.1.2';
+/** Au-delà, le SDK ne bloque pas votre programme : il rend la main avec RateLimitError. */
+const MAX_RETRY_AFTER_SECONDS = 60;
+/** Un même appel rejoué garde sa clé : c'est ce qui rend une reprise sans risque. */
+const MUTATING = new Set(['POST', 'PATCH', 'PUT', 'DELETE']);
+/** Le chemin unique de tous les appels : en-têtes, idempotence, reprises, erreurs. */
+export class Requester {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    async request(method, path, { query, body, options = {} } = {}) {
+        checkHeader('idempotencyKey', options.idempotencyKey);
+        checkHeader('requestId', options.requestId);
+        const url = this.#config.baseUrl + path + queryString(query);
+        const headers = {
+            Authorization: this.#config.authorization,
+            'X-Api-Key': this.#config.apiKey,
+            Accept: 'application/json',
+            'User-Agent': `fastermessage-node/${VERSION}`,
+        };
+        if (body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        if (options.requestId !== undefined)
+            headers['X-Request-Id'] = options.requestId;
+        let idempotencyKey = null;
+        if (MUTATING.has(method)) {
+            idempotencyKey = options.idempotencyKey ?? `sdk-${randomBytes(16).toString('hex')}`;
+            headers['Idempotency-Key'] = idempotencyKey;
+        }
+        const payload = body === undefined ? undefined : JSON.stringify(body);
+        const sleep = this.#config.sleep ?? defaultSleep;
+        for (let attempt = 0;; attempt++) {
+            let response;
+            let text;
+            try {
+                const timeout = AbortSignal.timeout(this.#config.timeout);
+                const fetchFn = this.#config.fetch ?? globalThis.fetch;
+                response = await fetchFn(url, {
+                    method,
+                    headers,
+                    ...(payload === undefined ? {} : { body: payload }),
+                    // Une redirection recopierait la clé d'API vers l'adresse de destination.
+                    redirect: 'manual',
+                    signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout,
+                });
+                text = await response.text();
+            }
+            catch (cause) {
+                if (options.signal?.aborted)
+                    throw options.signal.reason;
+                if (attempt >= this.#config.maxRetries) {
+                    const error = new ConnectionError(`Connexion à l'API impossible : ${describe(cause)}`, { cause });
+                    error.idempotencyKey = idempotencyKey;
+                    throw error;
+                }
+                await sleep(backoff(attempt));
+                continue;
+            }
+            if (response.status < 300)
+                return decode(response, text);
+            const failure = toError(response, text);
+            const wait = retryDelay(failure, attempt);
+            if (wait === null || attempt >= this.#config.maxRetries)
+                throw failure;
+            await sleep(wait);
+        }
+    }
+}
+function checkHeader(name, value) {
+    if (value !== undefined && !/^[\x20-\x7e]*$/.test(value)) {
+        throw new TypeError(`${name} contient des caractères invalides.`);
+    }
+}
+function queryString(query) {
+    if (!query)
+        return '';
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== null)
+            params.append(key, String(value));
+    }
+    const encoded = params.toString();
+    return encoded ? `?${encoded}` : '';
+}
+/**
+ * Reprise seulement si la même requête peut réussir plus tard. Un 429 sans
+ * `Retry-After` est le plafond OTP par numéro, à l'échelle de l'heure : le rejouer
+ * ne servirait à rien. Le 501 dit une fonction non servie, jamais une panne.
+ */
+function retryDelay(failure, attempt) {
+    if (failure.status === 429) {
+        if (failure.retryAfter === null || failure.retryAfter > MAX_RETRY_AFTER_SECONDS)
+            return null;
+        return failure.retryAfter * 1000;
+    }
+    if (failure.code === 'idempotency_key_in_flight')
+        return backoff(attempt);
+    if (failure.status >= 500 && failure.status !== 501)
+        return backoff(attempt);
+    return null;
+}
+function backoff(attempt) {
+    return Math.min(8000, 500 * 2 ** attempt) * (1 + Math.random() * 0.25);
+}
+function defaultSleep(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function describe(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+function decode(response, text) {
+    if (response.status === 204 || text.trim() === '')
+        return undefined;
+    const data = parse(text);
+    if (typeof data !== 'object' || data === null) {
+        throw new ServerError("Réponse illisible de l'API.", {
+            status: response.status,
+            code: 'invalid_response',
+            type: 'api_error',
+            requestId: response.headers.get('x-request-id'),
+        });
+    }
+    return data;
+}
+function parse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function stringOrNull(value) {
+    return typeof value === 'string' ? value : null;
+}
+function toError(response, text) {
+    const decoded = parse(text);
+    const error = decoded && typeof decoded.error === 'object' && decoded.error !== null ? decoded.error : {};
+    const status = response.status;
+    const retryAfter = response.headers.get('retry-after');
+    const ErrorClass = errorClass(status);
+    return new ErrorClass(stringOrNull(error.message) ?? `Erreur HTTP ${status}.`, {
+        status,
+        code: stringOrNull(error.code) ?? `http_${status}`,
+        type: stringOrNull(error.type) ?? '',
+        param: stringOrNull(error.param),
+        requestId: stringOrNull(error.request_id) ?? response.headers.get('x-request-id'),
+        retryAfter: retryAfter !== null && /^\d+$/.test(retryAfter.trim()) ? Number(retryAfter) : null,
+    });
+}
+function errorClass(status) {
+    switch (status) {
+        case 400: return InvalidRequestError;
+        case 401: return AuthenticationError;
+        case 402: return InsufficientBalanceError;
+        case 403: return PermissionError;
+        case 404: return NotFoundError;
+        case 409: return ConflictError;
+        case 429: return RateLimitError;
+        case 501: return NotImplementedError;
+        default: return status >= 500 ? ServerError : ApiError;
+    }
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,7 @@
+export { DEFAULT_BASE_URL, FasterMessage } from './client.js';
+export type { FasterMessageOptions } from './client.js';
+export * from './errors.js';
+export { VERSION } from './http.js';
+export type { RequestOptions } from './http.js';
+export { Webhook } from './webhook.js';
+export type * from './types.js';

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+export { DEFAULT_BASE_URL, FasterMessage } from './client.js';
+export * from './errors.js';
+export { VERSION } from './http.js';
+export { Webhook } from './webhook.js';

package/dist/esm/resources.d.ts

@@ -0,0 +1,60 @@
+import type { RequestOptions, Requester } from './http.js';
+import type { Balance, Contact, ContactBatchResult, ContactGroup, ContactQuery, CreateContactBatchParams, CreateContactGroupParams, CreateContactParams, CreditMovement, CreditQuery, Message, MessageQuery, Otp, Page, PageQuery, RequestOtpParams, SendEmailParams, SendMessageParams, SendSmsBatchParams, SendSmsParams, SmsBatchResult, UpdateContactGroupParams, UpdateContactParams } from './types.js';
+export declare class Sms {
+    #private;
+    constructor(http: Requester);
+    send(params: SendSmsParams, options?: RequestOptions): Promise<Message>;
+    /** Jusqu'à 500 lignes. Lisez toujours `errors` : un retour normal ne garantit pas que toutes soient parties. */
+    sendBatch(params: SendSmsBatchParams, options?: RequestOptions): Promise<SmsBatchResult>;
+}
+export declare class Email {
+    #private;
+    constructor(http: Requester);
+    send(params: SendEmailParams, options?: RequestOptions): Promise<Message>;
+}
+export declare class Messages {
+    #private;
+    constructor(http: Requester);
+    /** Envoi avec le canal en paramètre. WhatsApp et la voix répondent aujourd'hui `501`. */
+    send(params: SendMessageParams, options?: RequestOptions): Promise<Message>;
+    get(id: string): Promise<Message>;
+    list(query?: MessageQuery): Promise<Page<Message>>;
+    all(query?: MessageQuery): AsyncGenerator<Message, void, undefined>;
+}
+export declare class OtpResource {
+    #private;
+    constructor(http: Requester);
+    request(params: RequestOtpParams, options?: RequestOptions): Promise<Otp>;
+    verify(id: string, code: string): Promise<Otp>;
+}
+export declare class Contacts {
+    #private;
+    constructor(http: Requester);
+    create(params: CreateContactParams): Promise<Contact>;
+    /** Crée jusqu'à 500 contacts dans un groupe. */
+    createBatch(params: CreateContactBatchParams, options?: RequestOptions): Promise<ContactBatchResult>;
+    get(id: string): Promise<Contact>;
+    list(query?: ContactQuery): Promise<Page<Contact>>;
+    all(query?: ContactQuery): AsyncGenerator<Contact, void, undefined>;
+    update(id: string, params: UpdateContactParams): Promise<Contact>;
+    /** Suppression définitive. Ce n'est pas un désabonnement : pour cela, `consent: 'out'`. */
+    delete(id: string): Promise<void>;
+}
+export declare class ContactGroups {
+    #private;
+    constructor(http: Requester);
+    create(params: CreateContactGroupParams): Promise<ContactGroup>;
+    get(id: string): Promise<ContactGroup>;
+    list(query?: PageQuery): Promise<Page<ContactGroup>>;
+    all(query?: PageQuery): AsyncGenerator<ContactGroup, void, undefined>;
+    update(id: string, params: UpdateContactGroupParams): Promise<ContactGroup>;
+    /** Refusé en `409` tant que le groupe contient des contacts. */
+    delete(id: string): Promise<void>;
+}
+export declare class Account {
+    #private;
+    constructor(http: Requester);
+    balance(): Promise<Balance[]>;
+    credits(query?: CreditQuery): Promise<Page<CreditMovement>>;
+    allCredits(query?: CreditQuery): AsyncGenerator<CreditMovement, void, undefined>;
+}

package/dist/esm/resources.js

@@ -0,0 +1,126 @@
+function segment(id) {
+    // `..` changerait la route visée, et un identifiant vide viserait la collection.
+    if (id === '' || id === '.' || id === '..')
+        throw new TypeError('Identifiant de ressource invalide.');
+    return encodeURIComponent(id);
+}
+/** Parcourt toutes les pages, en demandant la suivante seulement quand il le faut. */
+async function* paginate(http, path, query) {
+    let cursor = query.cursor;
+    for (;;) {
+        const page = await http.request('GET', path, { query: { ...query, cursor } });
+        yield* page.data ?? [];
+        cursor = page.next_cursor;
+        if (page.has_more !== true || cursor === null || cursor === undefined)
+            return;
+    }
+}
+export class Sms {
+    #http;
+    constructor(http) { this.#http = http; }
+    send(params, options) {
+        return this.#http.request('POST', '/v2/sms/send', { body: params, options });
+    }
+    /** Jusqu'à 500 lignes. Lisez toujours `errors` : un retour normal ne garantit pas que toutes soient parties. */
+    sendBatch(params, options) {
+        return this.#http.request('POST', '/v2/sms/batch', { body: params, options });
+    }
+}
+export class Email {
+    #http;
+    constructor(http) { this.#http = http; }
+    send(params, options) {
+        return this.#http.request('POST', '/v2/email/send', { body: params, options });
+    }
+}
+export class Messages {
+    #http;
+    constructor(http) { this.#http = http; }
+    /** Envoi avec le canal en paramètre. WhatsApp et la voix répondent aujourd'hui `501`. */
+    send(params, options) {
+        return this.#http.request('POST', '/v2/messages', { body: params, options });
+    }
+    get(id) {
+        return this.#http.request('GET', `/v2/messages/${segment(id)}`);
+    }
+    list(query = {}) {
+        return this.#http.request('GET', '/v2/messages', { query });
+    }
+    all(query = {}) {
+        return paginate(this.#http, '/v2/messages', query);
+    }
+}
+export class OtpResource {
+    #http;
+    constructor(http) { this.#http = http; }
+    request(params, options) {
+        return this.#http.request('POST', '/v2/otp', { body: { channel: 'sms', ...params }, options });
+    }
+    verify(id, code) {
+        return this.#http.request('POST', '/v2/otp/verify', { body: { id, code } });
+    }
+}
+export class Contacts {
+    #http;
+    constructor(http) { this.#http = http; }
+    create(params) {
+        return this.#http.request('POST', '/v2/contacts', { body: params });
+    }
+    /** Crée jusqu'à 500 contacts dans un groupe. */
+    createBatch(params, options) {
+        return this.#http.request('POST', '/v2/contacts/batch', { body: params, options });
+    }
+    get(id) {
+        return this.#http.request('GET', `/v2/contacts/${segment(id)}`);
+    }
+    list(query = {}) {
+        return this.#http.request('GET', '/v2/contacts', { query });
+    }
+    all(query = {}) {
+        return paginate(this.#http, '/v2/contacts', query);
+    }
+    update(id, params) {
+        return this.#http.request('PATCH', `/v2/contacts/${segment(id)}`, { body: params });
+    }
+    /** Suppression définitive. Ce n'est pas un désabonnement : pour cela, `consent: 'out'`. */
+    async delete(id) {
+        await this.#http.request('DELETE', `/v2/contacts/${segment(id)}`);
+    }
+}
+export class ContactGroups {
+    #http;
+    constructor(http) { this.#http = http; }
+    create(params) {
+        return this.#http.request('POST', '/v2/contact-groups', { body: params });
+    }
+    get(id) {
+        return this.#http.request('GET', `/v2/contact-groups/${segment(id)}`);
+    }
+    list(query = {}) {
+        return this.#http.request('GET', '/v2/contact-groups', { query });
+    }
+    all(query = {}) {
+        return paginate(this.#http, '/v2/contact-groups', query);
+    }
+    update(id, params) {
+        return this.#http.request('PATCH', `/v2/contact-groups/${segment(id)}`, { body: params });
+    }
+    /** Refusé en `409` tant que le groupe contient des contacts. */
+    async delete(id) {
+        await this.#http.request('DELETE', `/v2/contact-groups/${segment(id)}`);
+    }
+}
+export class Account {
+    #http;
+    constructor(http) { this.#http = http; }
+    async balance() {
+        const { balances } = await this.#http.request('GET', '/v2/balance');
+        return balances ?? [];
+    }
+    credits(query = {}) {
+        return this.#http.request('GET', '/v2/credits', { query });
+    }
+    allCredits(query = {}) {
+        return paginate(this.#http, '/v2/credits', query);
+    }
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Les réponses gardent les noms de champs de l'API. La signature ouverte de chaque
+ * ressource rend disponible un champ ajouté par l'API sans mise à jour du SDK.
+ */
+export interface OpenRecord {
+    [field: string]: unknown;
+}
+export type Channel = 'sms' | 'email' | 'whatsapp' | 'voice';
+export type Consent = 'in' | 'out' | (string & {});
+export interface Page<T> extends OpenRecord {
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+export interface PageQuery {
+    limit?: number;
+    cursor?: string;
+}
+export interface MessageError extends OpenRecord {
+    code: string;
+    message: string;
+    provider_code: string | null;
+}
+export interface MessageRefund extends OpenRecord {
+    amount: number;
+    currency: string;
+    refunded_at: string;
+}
+export interface FallbackOutcome extends OpenRecord {
+    will_run: boolean;
+    reason: string | null;
+    message: string;
+    requested: Channel[];
+}
+export interface Message extends OpenRecord {
+    id: string;
+    channel: Channel;
+    status: string;
+    to: string;
+    from: string;
+    units: number;
+    price: number | null;
+    currency: string;
+    refund: MessageRefund | null;
+    client_reference: string | null;
+    fallback_of: string | null;
+    fallback?: FallbackOutcome | null;
+    error: MessageError | null;
+    created_at: string;
+    scheduled_at: string | null;
+    sent_at: string | null;
+    delivered_at: string | null;
+}
+interface SendCommon extends OpenRecord {
+    to: string;
+    fallback?: unknown[];
+    callback_url?: string;
+    scheduled_at?: string;
+    client_reference?: string;
+}
+export interface SendSmsParams extends SendCommon {
+    /** Sender ID approuvé : obligatoire, sans repli. */
+    from: string;
+    content: string | OpenRecord;
+}
+export interface EmailContent extends OpenRecord {
+    subject: string;
+    text?: string;
+    html?: string;
+}
+export interface SendEmailParams extends SendCommon {
+    from?: string;
+    content: EmailContent;
+}
+export interface SendMessageParams extends SendCommon {
+    channel: Channel;
+    from?: string;
+    content: unknown;
+}
+export interface SmsBatchLine extends OpenRecord {
+    to: string;
+    content?: string | OpenRecord;
+    from?: string;
+    client_reference?: string;
+    scheduled_at?: string;
+    callback_url?: string;
+}
+export interface SendSmsBatchParams extends OpenRecord {
+    /** De 1 à 500 lignes. */
+    messages: SmsBatchLine[];
+    from?: string;
+    content?: string | OpenRecord;
+    scheduled_at?: string;
+    callback_url?: string;
+}
+export interface BatchLineError extends OpenRecord {
+    index: number;
+    code: string;
+    message: string;
+    param?: string;
+    to?: string;
+}
+export interface SmsBatchResult extends OpenRecord {
+    total: number;
+    accepted: number;
+    rejected: number;
+    data: (Message & {
+        index: number;
+    })[];
+    /** Une entrée par ligne refusée : le reste du lot est bien parti. */
+    errors: BatchLineError[];
+}
+export interface MessageQuery extends PageQuery {
+    channel?: Channel;
+    status?: string;
+    [filter: string]: unknown;
+}
+export interface RequestOtpParams extends OpenRecord {
+    to: string;
+    /** `sms` par défaut. */
+    channel?: Channel;
+    from?: string;
+    length?: number;
+    ttl_seconds?: number;
+    template?: string;
+    client_reference?: string;
+}
+export interface Otp extends OpenRecord {
+    id: string;
+    status: string;
+    attempts_remaining: number;
+}
+export interface ContactFields extends OpenRecord {
+    email?: string;
+    whatsapp?: boolean;
+    consent?: Consent;
+    fields?: string[];
+}
+export interface CreateContactParams extends ContactFields {
+    group_id: string;
+    phone_number: string;
+}
+export interface UpdateContactParams extends OpenRecord {
+    group_id?: string;
+    phone_number?: string;
+    email?: string | null;
+    whatsapp?: boolean;
+    consent?: Consent;
+    fields?: string[];
+}
+export interface CreateContactBatchParams extends OpenRecord {
+    group_id: string;
+    /** De 1 à 500 lignes. */
+    contacts: (ContactFields & {
+        phone_number: string;
+    })[];
+    on_duplicate?: string;
+}
+export interface Contact extends OpenRecord {
+    id: string;
+    group_id: string;
+    phone_number: string;
+    consent: Consent;
+}
+export interface ContactBatchResult extends OpenRecord {
+    created: number;
+    invalid: number;
+}
+export interface ContactQuery extends PageQuery {
+    group_id?: string;
+    consent?: Consent;
+    search?: string;
+}
+export interface CreateContactGroupParams extends OpenRecord {
+    name: string;
+    fields?: string[];
+}
+export interface UpdateContactGroupParams extends OpenRecord {
+    name?: string;
+    fields?: string[];
+}
+export interface ContactGroup extends OpenRecord {
+    id: string;
+    name: string;
+    contacts_count: number;
+    fields: string[];
+}
+export interface Balance extends OpenRecord {
+    channel: Channel;
+    amount: number;
+    currency: string;
+}
+export interface CreditMovement extends OpenRecord {
+    id: string;
+    type: 'credit' | 'debit' | 'refund';
+    channel: Channel;
+    amount: number;
+    currency: string;
+}
+export interface CreditQuery extends PageQuery {
+    type?: 'credit' | 'debit' | 'refund';
+    [filter: string]: unknown;
+}
+export {};

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/webhook.d.ts

@@ -0,0 +1,11 @@
+/** Vérification des rappels reçus sur votre serveur. */
+export declare const Webhook: {
+    /**
+     * Vrai si le rappel vient bien de la plateforme.
+     *
+     * @param rawBody   le corps BRUT, avant tout décodage JSON
+     * @param signature l'en-tête `X-Fastermessage-Signature`
+     * @param secret    le secret généré dans « Intégration & API »
+     */
+    isGenuine(rawBody: string | Uint8Array, signature: string | null | undefined, secret: string): boolean;
+};

package/dist/esm/webhook.js

@@ -0,0 +1,18 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/** Vérification des rappels reçus sur votre serveur. */
+export const Webhook = {
+    /**
+     * Vrai si le rappel vient bien de la plateforme.
+     *
+     * @param rawBody   le corps BRUT, avant tout décodage JSON
+     * @param signature l'en-tête `X-Fastermessage-Signature`
+     * @param secret    le secret généré dans « Intégration & API »
+     */
+    isGenuine(rawBody, signature, secret) {
+        if (typeof signature !== 'string' || !secret)
+            return false;
+        const expected = Buffer.from(`sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`);
+        const received = Buffer.from(signature.trim());
+        return expected.length === received.length && timingSafeEqual(expected, received);
+    },
+};