@ankinize/sdk 0.0.0-stage → 1.0.0

package/dist/gen/types.gen.js

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { BATCH_LIMITS, type BatchOptions, type CreateNotesResult, type CreateTagsResult, createNotes, createTags, type DeleteCardsResult, type DeleteNotesResult, type DeleteTagsResult, deleteCards, deleteNotes, deleteTags, PartialBatchError, type UpdateCardsResult, type UpdateNotesResult, type UpdateTagsResult, updateCards, updateNotes, updateTags, } from "./batch.js";
+export { client } from "./gen/client.gen.js";
+export * from "./gen/public.gen.js";
+export type * from "./gen/types.gen.js";
+export { AnkinizeError } from "./runtime.js";
+export { createNote, type DeckName, generateTypes, type NoteFields, type NoteInput, type Register, } from "./typed.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { BATCH_LIMITS, createNotes, createTags, deleteCards, deleteNotes, deleteTags, PartialBatchError, updateCards, updateNotes, updateTags, } from "./batch.js";
+export { client } from "./gen/client.gen.js";
+export * from "./gen/public.gen.js";
+export { AnkinizeError } from "./runtime.js";
+export { createNote, generateTypes, } from "./typed.js";

package/dist/runtime.d.ts

@@ -0,0 +1,19 @@
+import type { CreateClientConfig } from "./gen/client.gen.js";
+/** Thrown for every answer that is not 2xx. */
+export declare class AnkinizeError extends Error {
+    /** HTTP status, for example 404 or 429. */
+    readonly status: number;
+    /** Machine-readable reason, for example `not_found` or `rate_limited`. */
+    readonly code: string;
+    /** The raw answer, for headers such as `Retry-After`. Its body is already read. */
+    readonly response: Response;
+    readonly name = "AnkinizeError";
+    constructor(
+    /** HTTP status, for example 404 or 429. */
+    status: number, 
+    /** Machine-readable reason, for example `not_found` or `rate_limited`. */
+    code: string, message: string, 
+    /** The raw answer, for headers such as `Retry-After`. Its body is already read. */
+    response: Response);
+}
+export declare const createClientConfig: CreateClientConfig;

package/dist/runtime.js

@@ -0,0 +1,57 @@
+/** Thrown for every answer that is not 2xx. */
+export class AnkinizeError extends Error {
+    status;
+    code;
+    response;
+    name = "AnkinizeError";
+    constructor(
+    /** HTTP status, for example 404 or 429. */
+    status, 
+    /** Machine-readable reason, for example `not_found` or `rate_limited`. */
+    code, message, 
+    /** The raw answer, for headers such as `Retry-After`. Its body is already read. */
+    response) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.response = response;
+    }
+}
+async function toError(response) {
+    const text = await response.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        // Not from the API (a proxy's error page, say): fall through to the status.
+    }
+    return new AnkinizeError(response.status, body?.error?.code ?? `http_${response.status}`, body?.error?.message ?? (text || response.statusText), response);
+}
+/**
+ * The generated client picks how to read a body from its Content-Type, and
+ * reads a type it does not know as JSON. Media files can be fonts, which it
+ * does not know, so they are handed over as plain bytes (a Blob).
+ */
+function asBytes(response) {
+    if (!response.headers.get("Content-Type")?.startsWith("font/"))
+        return response;
+    const headers = new Headers(response.headers);
+    headers.set("Content-Type", "application/octet-stream");
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+/** Looks `fetch` up per call, so a test double or a polyfill installed later still applies. */
+const apiFetch = async (input, init) => {
+    const response = await globalThis.fetch(input, init);
+    if (!response.ok)
+        throw await toError(response);
+    return asBytes(response);
+};
+export const createClientConfig = (config) => ({
+    ...config,
+    fetch: apiFetch,
+});

package/dist/typed.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Type-safe names. Out of the box a note is made by `notetypeName` and
+ * `deckName` strings and a `fields` object of strings. Describe your own
+ * collection once, with {@link generateTypes}, and the compiler also knows
+ * which note types and decks exist and which field keys each note type has.
+ */
+import { createNote as generatedCreateNote, listDecks } from "./gen/sdk.gen.js";
+import type { CreateNoteInput } from "./gen/types.gen.js";
+/**
+ * Filled in by your own declaration, usually the file {@link generateTypes}
+ * writes. Without it every name is a plain `string`.
+ *
+ * ```ts
+ * declare module "@ankinize/sdk" {
+ *   interface Register {
+ *     noteTypes: { Basic: "front" | "back"; "Cloze": "text" | "backExtra" };
+ *     decks: "Default" | "Languages::German";
+ *   }
+ * }
+ * ```
+ */
+export interface Register {
+}
+/** Note type name to the union of its field keys. */
+type NoteTypes = Register extends {
+    noteTypes: infer T extends Record<string, string>;
+} ? T : never;
+/** The names of your decks, or `string`. */
+export type DeckName = Register extends {
+    decks: infer D extends string;
+} ? D : string;
+/** The `fields` of a note by key; `Record<string, string>` until note types are registered. */
+export type NoteFields<Name extends string = string> = [NoteTypes] extends [
+    never
+] ? Record<string, string> : Name extends keyof NoteTypes ? {
+    [K in NoteTypes[Name]]?: string;
+} : Record<string, string>;
+type Base = Omit<CreateNoteInput, "notetypeName" | "notetypeId" | "deckName" | "deckId" | "fields">;
+type ByName = [NoteTypes] extends [never] ? {
+    notetypeName: string;
+    fields: NoteFields;
+} : {
+    [N in keyof NoteTypes & string]: {
+        notetypeName: N;
+        fields: NoteFields<N>;
+    };
+}[keyof NoteTypes & string];
+/** The id path is not checked against your note types; its fields are by key. */
+type ById = {
+    notetypeId: number;
+    fields: Record<string, string>;
+};
+/**
+ * A note to create: a note type by `notetypeName` (or `notetypeId`), at most
+ * one of `deckName` and `deckId`, and `fields` keyed by the note type's field
+ * keys.
+ */
+export type NoteInput = Base & ((ByName & {
+    notetypeId?: never;
+}) | (ById & {
+    notetypeName?: never;
+})) & ({
+    deckName?: DeckName;
+    deckId?: never;
+} | {
+    deckId?: number;
+    deckName?: never;
+});
+/**
+ * Creates a note and its cards. Same call as the generated operation, with
+ * `notetypeName`, `deckName` and `fields` checked against {@link Register}.
+ * Send `idempotencyKey` to make a retry safe.
+ */
+export declare const createNote: <ThrowOnError extends boolean = true>(parameters: NoteInput & {
+    idempotencyKey?: string;
+}, options?: Parameters<typeof generatedCreateNote<ThrowOnError>>[1]) => import("./gen/client/types.gen.js").RequestResult<import("./index.js").CreateNoteResponses, import("./index.js").CreateNoteErrors, ThrowOnError, "data">;
+/**
+ * The text of a declaration file that registers this collection's note types,
+ * their field keys and its decks. Write it anywhere the compiler reads:
+ *
+ * ```ts
+ * await Bun.write("ankinize.d.ts", await generateTypes());
+ * ```
+ *
+ * Run it again after you add a note type, a field or a deck.
+ */
+export declare function generateTypes(options?: {
+    client?: NonNullable<Parameters<typeof listDecks>[0]>["client"];
+}): Promise<string>;
+export {};

package/dist/typed.js

@@ -0,0 +1,51 @@
+/**
+ * Type-safe names. Out of the box a note is made by `notetypeName` and
+ * `deckName` strings and a `fields` object of strings. Describe your own
+ * collection once, with {@link generateTypes}, and the compiler also knows
+ * which note types and decks exist and which field keys each note type has.
+ */
+import { createNote as generatedCreateNote, getNoteType, listDecks, listNoteTypes, } from "./gen/sdk.gen.js";
+/**
+ * Creates a note and its cards. Same call as the generated operation, with
+ * `notetypeName`, `deckName` and `fields` checked against {@link Register}.
+ * Send `idempotencyKey` to make a retry safe.
+ */
+export const createNote = (parameters, options) => generatedCreateNote(parameters, options);
+/**
+ * The text of a declaration file that registers this collection's note types,
+ * their field keys and its decks. Write it anywhere the compiler reads:
+ *
+ * ```ts
+ * await Bun.write("ankinize.d.ts", await generateTypes());
+ * ```
+ *
+ * Run it again after you add a note type, a field or a deck.
+ */
+export async function generateTypes(options = {}) {
+    const request = { client: options.client };
+    const { decks } = await listDecks(request);
+    const { noteTypes } = await listNoteTypes(request);
+    const lines = [];
+    for (const { id, name } of noteTypes) {
+        if (id === undefined || name === undefined)
+            continue;
+        const { fields } = await getNoteType({ id }, request);
+        const keys = fields.map((f) => JSON.stringify(f.key)).join(" | ");
+        lines.push(`\t\t${JSON.stringify(name)}: ${keys || "never"};`);
+    }
+    const deckNames = decks.map((d) => JSON.stringify(d.name)).join(" | ");
+    return [
+        "// Generated by generateTypes() from @ankinize/sdk. Do not edit.",
+        "export {};",
+        "",
+        'declare module "@ankinize/sdk" {',
+        "\tinterface Register {",
+        "\t\tnoteTypes: {",
+        ...lines.map((l) => `\t${l}`),
+        "\t\t};",
+        `\t\tdecks: ${deckNames || "never"};`,
+        "\t}",
+        "}",
+        "",
+    ].join("\n");
+}

package/package.json

@@ -1,6 +1,44 @@
 {
-  "name": "@ankinize/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@ankinize/sdk",
+	"version": "1.0.0",
+	"description": "Official TypeScript SDK for the Ankinize REST API. Plain fetch, no runtime dependencies.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/0x0501/Ankinize.git",
+		"directory": "packages/sdk"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"sideEffects": false,
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"scripts": {
+		"generate": "bun install --cwd generator --frozen-lockfile && bun run --cwd generator generate && bun run scripts/idempotency-key.ts && bun run scripts/public-api.ts",
+		"build": "rm -rf dist && tsc -p tsconfig.build.json",
+		"check:dist": "bun run build && bun run scripts/check-dist.ts",
+		"prepack": "bun run build",
+		"test": "vitest run",
+		"test:unit": "vitest run",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome lint .",
+		"format": "biome format .",
+		"check": "biome check ."
+	},
+	"devDependencies": {
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.11"
+	}
+}