@ankinize/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @ankinize/sdk
 
-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.
+The official TypeScript SDK for the Ankinize REST API: one typed function per endpoint, standard `fetch` underneath, no dependencies, and a bundle that holds only the functions you import.
+
+```ts
+import { client, createNote, listDecks } from "@ankinize/sdk";
+
+client.setConfig({
+  baseUrl: "https://your-ankinize.example",
+  auth: process.env.ANKINIZE_API_KEY,
+});
+
+const { decks } = await listDecks();
+await createNote({
+  notetypeName: "Basic",
+  deckName: "Languages::German",
+  fields: { front: "der Hund", back: "the dog" },
+});
+```
+
+A note names its note type and deck (`notetypeName`, `deckName`, compared ignoring case) and gives `fields` as an object keyed by each field's name in camelCase (`Back Extra` is `backExtra`). Send `notetypeId` or `deckId` instead when you have the id: exactly one of `notetypeName` and `notetypeId`, and at most one of `deckName` and `deckId`. A key is a field's name cut into words at spaces, punctuation and lower-to-upper changes, the first word in lower case: `The field` is `theField`, `ab_x` is `abX`, `URLText` is `urlText`. A field's exact name works as a key too, and each note type lists its keys in `getNoteType`. Reading a note (`getNote`, `listNotes`) gives `fields` in the same shape, and `updateNote` takes the same object with only the fields that change.
+
+Parameters are camelCase everywhere. To make a write safe to retry, pass `idempotencyKey`; the SDK sends it as the `Idempotency-Key` header the API reads.
+
+## Type-safe names
+
+Out of the box the names are plain strings. To have the compiler check them, generate a declaration of your own collection and keep it in your project:
+
+```ts
+import { client, generateTypes } from "@ankinize/sdk";
+
+client.setConfig({ baseUrl, auth });
+await Bun.write("ankinize.d.ts", await generateTypes());
+```
+
+It declares your note types with their field keys, and your decks, by augmenting `Register`:
+
+```ts
+declare module "@ankinize/sdk" {
+  interface Register {
+    noteTypes: { Basic: "front" | "back"; Cloze: "text" | "backExtra" };
+    decks: "Default" | "Languages::German";
+  }
+}
+```
+
+After that `createNote` and `createNotes` reject a misspelt `notetypeName` or `deckName`, and a `fields` key that the chosen note type does not have. Run it again after you add a note type, a field or a deck. Notes made by `notetypeId` are not checked.
+
+## Batches
+
+`createNotes`, `updateNotes`, `deleteNotes`, `updateCards`, `deleteCards`, `createTags`, `updateTags` (a rename) and `deleteTags` take one item or an array, so you need not know the batch limits. They are the only way the SDK reaches the batch endpoints; the one-call functions behind them (`createNotesBatch`, ...) are not exported. They cut the array into calls the API accepts (200 notes, edits or tag names, 1000 ids or tag names to delete, and under 4 MiB of body), send them one after the other, wait and retry on `503`, `429` and `423` (honouring `Retry-After`), and return one answer with the entries in the order you gave them.
+
+```ts
+import { createNotes, deleteCards } from "@ankinize/sdk";
+
+const { created, failed, results } = await createNotes(notes);
+for (const r of results) if (!r.ok) console.log(r.index, r.error);
+```
+
+An entry the collection refuses is reported in `results`; the rest are written. `{ atomic: true }` writes all or nothing, and only works when everything fits one call (more throws a `RangeError` before sending). A call that cannot go on (a bad key, say) throws; if earlier calls had already gone through, it throws a `PartialBatchError` with their answers in `completed`. Options: `signal`, `client`, `maxRetries`, `maxRetryWaitMs`.
+
+A failed call throws an `AnkinizeError` (`status`, `code`, `message`, `response`). The user guide is at `/docs/sdk` on any Ankinize server.
+
+## Working on the SDK
+
+`openapi.json` is a snapshot of the document the REST API serves; `src/gen` is generated from it by [hey-api](https://heyapi.dev). Only `src/index.ts`, `src/runtime.ts`, `src/typed.ts` (the type-safe names) and `src/batch.ts` (the batch helpers) are written by hand. `scripts/idempotency-key.ts` runs after the generator and renames the `Idempotency-Key` parameter to `idempotencyKey`; the wire header keeps its name. `scripts/public-api.ts` then writes `src/gen/public.gen.ts`, the list `index.ts` exports, which leaves out the batch operations.
+
+```sh
+# After changing the REST API (a test fails when the snapshot is stale):
+bun run --filter @ankinize/web openapi:export
+bun run --filter @ankinize/sdk generate
+
+bun run --filter @ankinize/sdk test        # fetch-stub tests
+bun run --filter @ankinize/sdk check:dist  # builds; no hey-api import, no dependencies, tree-shakes
+```
+
+The generator lives in `generator/`, outside the workspace, because hey-api needs the TypeScript 6 compiler API and the workspace ships the native TypeScript 7. `generator/openapi-ts.config.ts` is where the SDK's spec differs from the docs' (no `HEAD`, no signed-link parameters, files typed as bytes, JSON bodies spread into the call, `ApiError` instead of `Error`).
+
+The generated client is bundled into `src/gen`; nothing from `@hey-api/*` is imported at runtime.

package/dist/batch.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Batch helpers: write one note or thousands with the same call, without
+ * knowing the batch endpoints' limits.
+ *
+ * Each helper takes one item or an array, cuts the array into the sizes the
+ * API accepts, sends the pieces one after the other, waits and retries when the
+ * server is busy or the rate limit asks to, and answers with the entries of all
+ * pieces in the order they were given.
+ *
+ * A piece that is refused for good (a bad key, a body that does not validate)
+ * stops the run by throwing. Pieces before it stay written; the error says which
+ * ones, see {@link PartialBatchError}.
+ */
+import { createNotesBatch } from "./gen/sdk.gen.js";
+import type { CreateNotesBatchItem, CreateTagsBatchItem, UpdateCardInput, UpdateCardsBatchItem, UpdateNotesBatchEntry, UpdateNotesBatchItem, UpdateTagsBatchEntry, UpdateTagsBatchItem } from "./gen/types.gen.js";
+import type { NoteInput } from "./typed.js";
+/** What the API accepts in one call, per endpoint. */
+export declare const BATCH_LIMITS: {
+    readonly notes: 200;
+    readonly noteUpdates: 200;
+    readonly tags: 200;
+    readonly cards: 1000;
+    readonly deletes: 1000;
+};
+type GenOptions = NonNullable<Parameters<typeof createNotesBatch<true>>[1]>;
+export interface BatchOptions {
+    /**
+     * Write all or nothing. Only possible when everything fits one call
+     * (`BATCH_LIMITS`): a larger array throws a `RangeError` before anything is
+     * sent. When an entry is refused, the answer has `committed: false` and
+     * every entry in `results`, as the API sends it.
+     */
+    atomic?: boolean;
+    /** Stops waiting and sending. The piece in flight is not recalled. */
+    signal?: AbortSignal;
+    /** A client other than the shared one. */
+    client?: GenOptions["client"];
+    /** How often one piece is retried after `503`, `429` or `423`. Default 5. */
+    maxRetries?: number;
+    /**
+     * The longest wait for a retry, in milliseconds. A `Retry-After` beyond it
+     * (a daily rate limit, say) throws the error instead. Default 60 000.
+     */
+    maxRetryWaitMs?: number;
+}
+/** A run that stopped at a piece the API refused. The pieces before it were written. */
+export declare class PartialBatchError extends Error {
+    /**
+     * The answers of the pieces that went through, in order: the
+     * `results` of a create, edit or card update, the id lists of a delete.
+     */
+    readonly completed: unknown[];
+    /** How many of the given items those pieces held. */
+    readonly completedItems: number;
+    /** The error that stopped the run. */
+    readonly cause: unknown;
+    readonly name = "PartialBatchError";
+    constructor(
+    /**
+     * The answers of the pieces that went through, in order: the
+     * `results` of a create, edit or card update, the id lists of a delete.
+     */
+    completed: unknown[], 
+    /** How many of the given items those pieces held. */
+    completedItems: number, 
+    /** The error that stopped the run. */
+    cause: unknown);
+}
+export interface CreateNotesResult {
+    /** Whether anything was written. */
+    committed: boolean;
+    created: number;
+    failed: number;
+    /** One entry per note given, in order; `index` is the position in what you passed. */
+    results: CreateNotesBatchItem[];
+}
+/** Creates one note or many. Entries the collection refuses are reported in `results`. */
+export declare function createNotes(notes: NoteInput | readonly NoteInput[], options?: BatchOptions): Promise<CreateNotesResult>;
+export interface UpdateNotesResult {
+    committed: boolean;
+    /** How many notes differed from what was stored and were written. */
+    changed: number;
+    failed: number;
+    /** One entry per update given, in order; `index` is the position in what you passed. */
+    results: UpdateNotesBatchItem[];
+}
+/**
+ * Edits one note or many. Each entry names the note by `id` and may carry
+ * `fields`, `tags`, or `addTags` and `removeTags`. A note may appear once.
+ */
+export declare function updateNotes(updates: UpdateNotesBatchEntry | readonly UpdateNotesBatchEntry[], options?: BatchOptions): Promise<UpdateNotesResult>;
+export interface DeleteNotesResult {
+    deleted: number;
+    deletedNoteIds: number[];
+    /** Every card that was made from them. */
+    deletedCardIds: number[];
+    /** Ids that did not exist and were ignored. */
+    missingNoteIds: number[];
+}
+/** Deletes one note or many, with their cards. Missing ids are listed, not errors. */
+export declare function deleteNotes(ids: number | readonly number[], options?: BatchOptions): Promise<DeleteNotesResult>;
+export interface UpdateCardsResult {
+    committed: boolean;
+    /** How many cards differed from what was stored and were written. */
+    changed: number;
+    failed: number;
+    /** One entry per distinct id given, in the order of first appearance. */
+    results: UpdateCardsBatchItem[];
+}
+/** Applies one change (a flag, a deck, suspended, buried) to one card or many. */
+export declare function updateCards(ids: number | readonly number[], patch: UpdateCardInput, options?: BatchOptions): Promise<UpdateCardsResult>;
+export interface DeleteCardsResult {
+    deleted: number;
+    deletedCardIds: number[];
+    /** Notes deleted because their last card went. */
+    deletedNoteIds: number[];
+    /** Ids that did not exist and were ignored. */
+    missingCardIds: number[];
+}
+/** Deletes one card or many. A note whose last card goes is deleted too. */
+export declare function deleteCards(ids: number | readonly number[], options?: BatchOptions): Promise<DeleteCardsResult>;
+export interface CreateTagsResult {
+    committed: boolean;
+    /** How many tags did not exist and were made. */
+    created: number;
+    failed: number;
+    /** One entry per name given, in order; `created: false` marks a tag that already existed. */
+    results: CreateTagsBatchItem[];
+}
+/**
+ * Creates one tag or many, without putting them on a note. A name that exists
+ * (ignoring case) is reported with `created: false`, not an error.
+ */
+export declare function createTags(names: string | readonly string[], options?: BatchOptions): Promise<CreateTagsResult>;
+export interface UpdateTagsResult {
+    committed: boolean;
+    /** How many renames were made. */
+    renamed: number;
+    failed: number;
+    /** One entry per rename given, in order; `index` is the position in what you passed. */
+    results: UpdateTagsBatchItem[];
+}
+/**
+ * Renames one tag or many, each with its nested tags. Renames in one run may
+ * not overlap: a tag and one nested under it cannot both be renamed.
+ */
+export declare function updateTags(updates: UpdateTagsBatchEntry | readonly UpdateTagsBatchEntry[], options?: BatchOptions): Promise<UpdateTagsResult>;
+export interface DeleteTagsResult {
+    deleted: number;
+    /** The tags removed, nested ones included. */
+    deletedTags: string[];
+    /** Names that matched no tag and were ignored. */
+    missingNames: string[];
+}
+/** Deletes one tag or many, with their nested tags, and takes them off every note. */
+export declare function deleteTags(names: string | readonly string[], options?: BatchOptions): Promise<DeleteTagsResult>;
+export {};

package/dist/batch.js

@@ -0,0 +1,263 @@
+/**
+ * Batch helpers: write one note or thousands with the same call, without
+ * knowing the batch endpoints' limits.
+ *
+ * Each helper takes one item or an array, cuts the array into the sizes the
+ * API accepts, sends the pieces one after the other, waits and retries when the
+ * server is busy or the rate limit asks to, and answers with the entries of all
+ * pieces in the order they were given.
+ *
+ * A piece that is refused for good (a bad key, a body that does not validate)
+ * stops the run by throwing. Pieces before it stay written; the error says which
+ * ones, see {@link PartialBatchError}.
+ */
+import { createNotesBatch, createTagsBatch, deleteCardsBatch, deleteNotesBatch, deleteTagsBatch, updateCardsBatch, updateNotesBatch, updateTagsBatch, } from "./gen/sdk.gen.js";
+import { AnkinizeError } from "./runtime.js";
+/** What the API accepts in one call, per endpoint. */
+export const BATCH_LIMITS = {
+    notes: 200,
+    noteUpdates: 200,
+    tags: 200,
+    cards: 1000,
+    deletes: 1000,
+};
+/** A run that stopped at a piece the API refused. The pieces before it were written. */
+export class PartialBatchError extends Error {
+    completed;
+    completedItems;
+    cause;
+    name = "PartialBatchError";
+    constructor(
+    /**
+     * The answers of the pieces that went through, in order: the
+     * `results` of a create, edit or card update, the id lists of a delete.
+     */
+    completed, 
+    /** How many of the given items those pieces held. */
+    completedItems, 
+    /** The error that stopped the run. */
+    cause) {
+        super(`Stopped after ${completedItems} items were written: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.completed = completed;
+        this.completedItems = completedItems;
+        this.cause = cause;
+    }
+}
+const RETRY_STATUSES = new Set([423, 429, 503]);
+function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Seconds from a `Retry-After` header, or null when it is not a number of seconds. */
+function retryAfterMs(error) {
+    const raw = error.response.headers.get("Retry-After");
+    if (raw === null)
+        return null;
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : null;
+}
+async function sendWithRetry(send, options) {
+    const maxRetries = options.maxRetries ?? 5;
+    const maxWait = options.maxRetryWaitMs ?? 60_000;
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await send();
+        }
+        catch (error) {
+            if (!(error instanceof AnkinizeError) ||
+                !RETRY_STATUSES.has(error.status) ||
+                attempt >= maxRetries) {
+                throw error;
+            }
+            // These answers mean nothing was written, so sending again is safe.
+            const wait = retryAfterMs(error) ?? Math.min(2 ** attempt * 1000, maxWait);
+            if (wait > maxWait)
+                throw error;
+            await abortableSleep(wait, options.signal);
+        }
+    }
+}
+/**
+ * An atomic call that an entry spoiled is answered `422` with the result as its
+ * body, which the client throws like any error. Hands the result back instead.
+ */
+function refusedResult(error) {
+    if (!(error instanceof AnkinizeError) || error.status !== 422)
+        return null;
+    try {
+        const body = JSON.parse(error.message);
+        return Array.isArray(body.results) ? body : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A call's body is limited to 8 MiB; pieces stay well under it. */
+const MAX_PIECE_BYTES = 4 * 1024 * 1024;
+const encoder = new TextEncoder();
+/** Cuts at `size` items, and for items that carry content also before a piece outgrows `MAX_PIECE_BYTES`. */
+function pieces(items, size, bySize) {
+    const out = [];
+    let current = [];
+    let bytes = 0;
+    for (const item of items) {
+        const weight = bySize ? encoder.encode(JSON.stringify(item)).length : 0;
+        if (current.length > 0 &&
+            (current.length >= size || bytes + weight > MAX_PIECE_BYTES)) {
+            out.push(current);
+            current = [];
+            bytes = 0;
+        }
+        current.push(item);
+        bytes += weight;
+    }
+    if (current.length > 0)
+        out.push(current);
+    return out;
+}
+/** Sends every piece in turn and returns the answers, or throws a `PartialBatchError`. */
+async function run(items, size, options, send, bySize = false) {
+    const parts = pieces(items, size, bySize);
+    if (options.atomic && parts.length > 1) {
+        throw new RangeError(`atomic needs everything in one call (at most ${size} items and ${MAX_PIECE_BYTES} bytes); got ${items.length} items in ${parts.length} calls`);
+    }
+    const answers = [];
+    const offsets = [];
+    let done = 0;
+    for (const piece of parts) {
+        options.signal?.throwIfAborted();
+        let answer;
+        try {
+            answer = await sendWithRetry(() => send(piece), options);
+        }
+        catch (error) {
+            const refused = options.atomic ? refusedResult(error) : null;
+            if (!refused) {
+                if (answers.length === 0)
+                    throw error;
+                throw new PartialBatchError(answers, done, error);
+            }
+            answer = refused;
+        }
+        answers.push(answer);
+        offsets.push(done);
+        done += piece.length;
+    }
+    return { answers, offsets };
+}
+const many = (items) => Array.isArray(items) ? items : [items];
+const distinct = (items) => [
+    ...new Set(many(items)),
+];
+const request = (options) => ({
+    client: options.client,
+    signal: options.signal,
+});
+/** Creates one note or many. Entries the collection refuses are reported in `results`. */
+export async function createNotes(notes, options = {}) {
+    const { answers, offsets } = await run(many(notes), BATCH_LIMITS.notes, options, (piece) => createNotesBatch({ notes: piece, atomic: options.atomic }, request(options)), true);
+    return {
+        committed: answers.some((a) => a.committed),
+        created: answers.reduce((n, a) => n + a.created, 0),
+        failed: answers.reduce((n, a) => n + a.failed, 0),
+        results: answers.flatMap((a, i) => a.results.map((r) => ({ ...r, index: r.index + (offsets[i] ?? 0) }))),
+    };
+}
+/**
+ * Edits one note or many. Each entry names the note by `id` and may carry
+ * `fields`, `tags`, or `addTags` and `removeTags`. A note may appear once.
+ */
+export async function updateNotes(updates, options = {}) {
+    const { answers, offsets } = await run(many(updates), BATCH_LIMITS.noteUpdates, options, (piece) => updateNotesBatch({ updates: piece, atomic: options.atomic }, request(options)), true);
+    return {
+        committed: answers.some((a) => a.committed),
+        changed: answers.reduce((n, a) => n + a.changed, 0),
+        failed: answers.reduce((n, a) => n + a.failed, 0),
+        results: answers.flatMap((a, i) => a.results.map((r) => ({ ...r, index: r.index + (offsets[i] ?? 0) }))),
+    };
+}
+/** Deletes one note or many, with their cards. Missing ids are listed, not errors. */
+export async function deleteNotes(ids, options = {}) {
+    const { answers } = await run(distinct(ids), BATCH_LIMITS.deletes, { ...options, atomic: false }, async (piece) => {
+        const a = await deleteNotesBatch({ ids: piece }, request(options));
+        return { ...a, results: [] };
+    });
+    return {
+        deleted: answers.reduce((n, a) => n + a.deleted, 0),
+        deletedNoteIds: answers.flatMap((a) => a.deletedNoteIds),
+        deletedCardIds: answers.flatMap((a) => a.deletedCardIds),
+        missingNoteIds: answers.flatMap((a) => a.missingNoteIds),
+    };
+}
+/** Applies one change (a flag, a deck, suspended, buried) to one card or many. */
+export async function updateCards(ids, patch, options = {}) {
+    const { answers } = await run(distinct(ids), BATCH_LIMITS.cards, options, (piece) => updateCardsBatch({ ids: piece, patch, atomic: options.atomic }, request(options)));
+    return {
+        committed: answers.some((a) => a.committed),
+        changed: answers.reduce((n, a) => n + a.changed, 0),
+        failed: answers.reduce((n, a) => n + a.failed, 0),
+        results: answers.flatMap((a) => a.results),
+    };
+}
+/** Deletes one card or many. A note whose last card goes is deleted too. */
+export async function deleteCards(ids, options = {}) {
+    const { answers } = await run(distinct(ids), BATCH_LIMITS.deletes, { ...options, atomic: false }, async (piece) => {
+        const a = await deleteCardsBatch({ ids: piece }, request(options));
+        return { ...a, results: [] };
+    });
+    return {
+        deleted: answers.reduce((n, a) => n + a.deleted, 0),
+        deletedCardIds: answers.flatMap((a) => a.deletedCardIds),
+        deletedNoteIds: answers.flatMap((a) => a.deletedNoteIds),
+        missingCardIds: answers.flatMap((a) => a.missingCardIds),
+    };
+}
+/**
+ * Creates one tag or many, without putting them on a note. A name that exists
+ * (ignoring case) is reported with `created: false`, not an error.
+ */
+export async function createTags(names, options = {}) {
+    const { answers, offsets } = await run(many(names), BATCH_LIMITS.tags, options, (piece) => createTagsBatch({ names: piece, atomic: options.atomic }, request(options)));
+    return {
+        committed: answers.some((a) => a.committed),
+        created: answers.reduce((n, a) => n + a.created, 0),
+        failed: answers.reduce((n, a) => n + a.failed, 0),
+        results: answers.flatMap((a, i) => a.results.map((r) => ({ ...r, index: r.index + (offsets[i] ?? 0) }))),
+    };
+}
+/**
+ * Renames one tag or many, each with its nested tags. Renames in one run may
+ * not overlap: a tag and one nested under it cannot both be renamed.
+ */
+export async function updateTags(updates, options = {}) {
+    const { answers, offsets } = await run(many(updates), BATCH_LIMITS.tags, options, (piece) => updateTagsBatch({ updates: piece, atomic: options.atomic }, request(options)));
+    return {
+        committed: answers.some((a) => a.committed),
+        renamed: answers.reduce((n, a) => n + a.renamed, 0),
+        failed: answers.reduce((n, a) => n + a.failed, 0),
+        results: answers.flatMap((a, i) => a.results.map((r) => ({ ...r, index: r.index + (offsets[i] ?? 0) }))),
+    };
+}
+/** Deletes one tag or many, with their nested tags, and takes them off every note. */
+export async function deleteTags(names, options = {}) {
+    const { answers } = await run(distinct(names), BATCH_LIMITS.deletes, { ...options, atomic: false }, async (piece) => {
+        const a = await deleteTagsBatch({ names: piece }, request(options));
+        return { ...a, results: [] };
+    });
+    return {
+        deleted: answers.reduce((n, a) => n + a.deleted, 0),
+        deletedTags: answers.flatMap((a) => a.deletedTags),
+        missingNames: answers.flatMap((a) => a.missingNames),
+    };
+}

package/dist/gen/client/client.gen.d.ts

@@ -0,0 +1,2 @@
+import type { Client, Config } from './types.gen.js';
+export declare const createClient: (config?: Config) => Client;