@szymonpiatek/courier 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @szymonpiatek/courier
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Klient TypeScript do API [Couriera](https://github.com/SzymonPiatek/Courier): wysyłka maili przez jeden endpoint zamiast własnej konfiguracji SMTP. Bez zależności, na natywnym `fetch` (Node 22+, przeglądarki).
+
+```bash
+npm install @szymonpiatek/courier
+```
+
+## Użycie
+
+Klucz API (`crk_…`) tworzysz w panelu Couriera (Klucze API) i przypisujesz do kont SMTP, z których może wysyłać.
+
+```ts
+import { createClient, CourierError } from '@szymonpiatek/courier';
+
+const courier = createClient({
+  baseUrl: 'https://mail.example.com', // bez /v1
+  apiKey: process.env.COURIER_API_KEY!,
+});
+
+try {
+  const { id, status } = await courier.messages.send(
+    {
+      to: 'klient@example.com',
+      subject: 'Potwierdzenie',
+      html: '<p>Dziękujemy!</p>',
+      attachments: [{ filename: 'faktura.pdf', content: pdfBytes }], // bajty albo base64
+    },
+    { idempotencyKey: 'zamowienie-4821' },
+  );
+} catch (err) {
+  if (err instanceof CourierError && err.retryable) {
+    // 429 / 503 / błąd sieci: ponów po err.retryAfter sekundach
+  }
+}
+```
+
+Odpowiedź `202` (`status: 'QUEUED'`) oznacza przyjęcie do kolejki. Wysyła ją osobny worker, więc stan sprawdzisz przez `courier.messages.get(id)`.
+
+## API
+
+| Metoda                           | Opis                                                                         |
+| -------------------------------- | ---------------------------------------------------------------------------- |
+| `messages.send(input, options?)` | Dodaje wiadomość do kolejki. `idempotencyKey` pozwala bezpiecznie ponawiać   |
+| `messages.get(id)`               | Szczegóły wiadomości wraz ze zdarzeniami                                     |
+| `messages.list(query?)`          | Strona wyników (filtry: `status`, `account`, `from`, `to`, `since`, `until`) |
+| `messages.iterate(query?)`       | Iterator po wszystkich stronach, od najnowszych                              |
+
+`CourierError` ma pola `status`, `code`, `retryable` i `retryAfter`. Opcje klienta: `fetch` (własna implementacja) i `timeoutMs` (domyślnie 30 s).
+
+## Licencja
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+import type { ListQuery, MessageDetail, MessagePage, MessageSummary, SendMessageInput, SendOptions, SendResult } from './types.js';
+export interface ClientOptions {
+    /** Adres Couriera, np. https://mail.example.com (bez /v1). */
+    baseUrl: string;
+    /** Klucz API z panelu (crk_…). */
+    apiKey: string;
+    /** Własna implementacja fetch (testy, proxy); domyślnie globalna. */
+    fetch?: typeof fetch;
+    /** Limit czasu jednego zapytania (domyślnie 30 s). */
+    timeoutMs?: number;
+}
+export interface CourierClient {
+    messages: {
+        send(input: SendMessageInput, options?: SendOptions): Promise<SendResult>;
+        get(id: string, options?: {
+            signal?: AbortSignal;
+        }): Promise<MessageDetail>;
+        list(query?: ListQuery, options?: {
+            signal?: AbortSignal;
+        }): Promise<MessagePage>;
+        /** Przechodzi po wszystkich stronach wyników, od najnowszych. */
+        iterate(query?: Omit<ListQuery, 'cursor'>): AsyncGenerator<MessageSummary, void, void>;
+    };
+}
+export declare function createClient(options: ClientOptions): CourierClient;

package/dist/client.js

@@ -0,0 +1,81 @@
+import { CourierError } from './errors.js';
+import { toRequestBody } from './encode.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+function queryString(query) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        params.set(key, value instanceof Date ? value.toISOString() : String(value));
+    }
+    const text = params.toString();
+    return text ? `?${text}` : '';
+}
+export function createClient(options) {
+    const base = options.baseUrl.replace(/\/+$/, '');
+    const doFetch = options.fetch ?? fetch;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    async function request(path, init) {
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+        let res;
+        try {
+            res = await doFetch(`${base}${path}`, {
+                method: init.method ?? 'GET',
+                signal,
+                headers: {
+                    Authorization: `Bearer ${options.apiKey}`,
+                    Accept: 'application/json',
+                    ...(init.body !== undefined && { 'Content-Type': 'application/json' }),
+                    ...init.headers,
+                },
+                body: init.body === undefined ? undefined : JSON.stringify(init.body),
+            });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new CourierError(0, 'network_error', `Request failed: ${reason}`);
+        }
+        const body = await res.json().catch(() => null);
+        if (!res.ok) {
+            const error = body
+                ?.error;
+            throw new CourierError(res.status, error?.code ?? 'error', error?.message ?? `HTTP ${res.status}`, error?.issues, Number(res.headers.get('Retry-After')) || undefined);
+        }
+        return { status: res.status, body };
+    }
+    const client = {
+        messages: {
+            async send(input, sendOptions = {}) {
+                const { status, body } = await request('/v1/messages', {
+                    method: 'POST',
+                    body: toRequestBody(input),
+                    signal: sendOptions.signal,
+                    headers: sendOptions.idempotencyKey
+                        ? { 'Idempotency-Key': sendOptions.idempotencyKey }
+                        : undefined,
+                });
+                const receipt = body;
+                return { id: receipt.id, status: receipt.status, replayed: status === 200 };
+            },
+            async get(id, getOptions = {}) {
+                const { body } = await request(`/v1/messages/${encodeURIComponent(id)}`, getOptions);
+                return body;
+            },
+            async list(query = {}, listOptions = {}) {
+                const { body } = await request(`/v1/messages${queryString(query)}`, listOptions);
+                return body;
+            },
+            async *iterate(query = {}) {
+                let cursor;
+                do {
+                    const page = await client.messages.list({ ...query, cursor });
+                    yield* page.data;
+                    cursor = page.nextCursor ?? undefined;
+                } while (cursor);
+            },
+        },
+    };
+    return client;
+}
+//# sourceMappingURL=client.js.map

package/dist/encode.d.ts

@@ -0,0 +1,5 @@
+import type { SendMessageInput } from './types.js';
+/** Bajty -> base64 w Node i w przeglądarce (porcjami, żeby nie przepełnić stosu). */
+export declare function toBase64(bytes: Uint8Array): string;
+/** Ciało zapytania `POST /v1/messages`: załączniki jako base64, reszta bez zmian. */
+export declare function toRequestBody(input: SendMessageInput): Record<string, unknown>;

package/dist/encode.js

@@ -0,0 +1,25 @@
+/** Bajty -> base64 w Node i w przeglądarce (porcjami, żeby nie przepełnić stosu). */
+export function toBase64(bytes) {
+    if (typeof Buffer !== 'undefined')
+        return Buffer.from(bytes).toString('base64');
+    let binary = '';
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(binary);
+}
+/** Ciało zapytania `POST /v1/messages`: załączniki jako base64, reszta bez zmian. */
+export function toRequestBody(input) {
+    const { attachments, ...rest } = input;
+    return {
+        ...rest,
+        ...(attachments && {
+            attachments: attachments.map(({ filename, content, contentType }) => ({
+                filename,
+                ...(contentType && { contentType }),
+                content: typeof content === 'string' ? content : toBase64(content),
+            })),
+        }),
+    };
+}
+//# sourceMappingURL=encode.js.map

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+/** Błąd odpowiedzi API (status 4xx/5xx) albo problem z połączeniem (status 0). */
+export declare class CourierError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: {
+        path: string;
+        message: string;
+    }[] | undefined;
+    /** Sekundy do ponowienia (nagłówek Retry-After), np. przy 429. */
+    readonly retryAfter?: number | undefined;
+    constructor(status: number, code: string, message: string, details?: {
+        path: string;
+        message: string;
+    }[] | undefined, 
+    /** Sekundy do ponowienia (nagłówek Retry-After), np. przy 429. */
+    retryAfter?: number | undefined);
+    /** Warto ponowić: limit zapytań, niedostępna kolejka albo błąd sieci. */
+    get retryable(): boolean;
+}

package/dist/errors.js

@@ -0,0 +1,22 @@
+/** Błąd odpowiedzi API (status 4xx/5xx) albo problem z połączeniem (status 0). */
+export class CourierError extends Error {
+    status;
+    code;
+    details;
+    retryAfter;
+    constructor(status, code, message, details, 
+    /** Sekundy do ponowienia (nagłówek Retry-After), np. przy 429. */
+    retryAfter) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.retryAfter = retryAfter;
+        this.name = 'CourierError';
+    }
+    /** Warto ponowić: limit zapytań, niedostępna kolejka albo błąd sieci. */
+    get retryable() {
+        return this.status === 0 || this.status === 429 || this.status === 503;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createClient, type ClientOptions, type CourierClient } from './client.js';
+export { CourierError } from './errors.js';
+export { toRequestBody } from './encode.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createClient } from './client.js';
+export { CourierError } from './errors.js';
+export { toRequestBody } from './encode.js';
+//# sourceMappingURL=index.js.map

package/dist/types.d.ts

@@ -0,0 +1,79 @@
+export type MessageStatus = 'QUEUED' | 'SENDING' | 'SENT' | 'FAILED';
+/** Załącznik w zapytaniu: `content` to bajty albo gotowy napis base64. */
+export interface AttachmentInput {
+    filename: string;
+    content: string | Uint8Array;
+    /** Domyślnie application/octet-stream. */
+    contentType?: string;
+}
+export interface SendMessageInput {
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    /** Adres nadawcy; potrzebny, gdy klucz ma kilka kont (albo podaj `account`). */
+    from?: string;
+    account?: string;
+    headers?: Record<string, string>;
+    attachments?: AttachmentInput[];
+}
+export interface SendOptions {
+    /** Ten sam klucz zwraca istniejącą wiadomość zamiast tworzyć drugą (bezpieczne ponowienia). */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+export interface SendResult {
+    id: string;
+    status: MessageStatus;
+    /** true, gdy serwer rozpoznał powtórzone zapytanie (ten sam Idempotency-Key). */
+    replayed: boolean;
+}
+export interface MessageSummary {
+    id: string;
+    accountId: string;
+    status: MessageStatus;
+    from: string;
+    to: string[];
+    subject: string;
+    attempts: number;
+    lastError: string | null;
+    createdAt: string;
+    sentAt: string | null;
+}
+export interface MessageEvent {
+    type: 'QUEUED' | 'ATTEMPT' | 'SENT' | 'FAILED' | 'OPENED' | 'CLICKED';
+    detail: unknown;
+    createdAt: string;
+}
+export interface MessageDetail extends MessageSummary {
+    cc: string[];
+    bcc: string[];
+    html: string | null;
+    text: string | null;
+    headers: Record<string, string> | null;
+    messageId: string | null;
+    attachments: {
+        id: string;
+        filename: string;
+        contentType: string;
+        size: number;
+    }[];
+    events: MessageEvent[];
+}
+export interface ListQuery {
+    status?: MessageStatus;
+    account?: string;
+    from?: string;
+    to?: string;
+    since?: Date | string;
+    until?: Date | string;
+    /** 1–100, domyślnie 25. */
+    limit?: number;
+    cursor?: string;
+}
+export interface MessagePage {
+    data: MessageSummary[];
+    nextCursor: string | null;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@szymonpiatek/courier",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Klient TypeScript do API Couriera (bez zależności, natywny fetch).",
+  "keywords": [
+    "courier",
+    "email",
+    "smtp",
+    "api-client"
+  ],
+  "license": "MIT",
+  "author": "Szymon Piątek",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SzymonPiatek/Courier.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/SzymonPiatek/Courier/tree/main/packages/client#readme",
+  "bugs": {
+    "url": "https://github.com/SzymonPiatek/Courier/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "vitest": "^5.0.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }