@mycroblog/mykit 0.0.0-placeholder.0

package/dist/transport.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: MIT
+import { idempotencyKeyHeader } from "./idempotency.js";
+import { isAbort } from "./oauth.js";
+import { NetworkError } from "./problem.js";
+const defaultMaxRetries = 3;
+const defaultMaxWait = 60_000;
+/**
+ * The fetch of the generated client. For each request it adds the access token; after a 401 it refreshes the token
+ * once and sends the request again; after a 429 or 503 it waits and retries the requests that are safe to repeat;
+ * and it turns a failure to get an answer into a NetworkError. Every middleware of the client sees only the last
+ * answer.
+ */
+export function createTransport({ fetch, tokenSource, retry, sleep = sleepSignal }) {
+    const maxRetries = retry?.disabled === true ? 0 : (retry?.maxRetries ?? defaultMaxRetries);
+    const maxWait = retry?.maxWait ?? defaultMaxWait;
+    return async (request) => {
+        const method = request.method.toUpperCase();
+        const retryable = method === "GET" || method === "HEAD" || request.headers.has(idempotencyKeyHeader);
+        // An unsent copy to send again: a body can be read only once.
+        const copy = request.clone();
+        let refreshed = false;
+        let renewed = null;
+        let retries = 0;
+        for (let attempt = 0;; attempt++) {
+            const r = attempt === 0 ? request : copy.clone();
+            let token = null;
+            if (tokenSource !== undefined) {
+                token = renewed ?? (await tokenSource.getAccessToken());
+                renewed = null;
+                if (token !== null)
+                    r.headers.set("Authorization", `Bearer ${token}`);
+            }
+            let response;
+            try {
+                response = await fetch(r);
+            }
+            catch (error) {
+                if (isAbort(error) || request.signal.aborted)
+                    throw error;
+                throw new NetworkError(method, request.url, error);
+            }
+            if (response.status === 401 && token !== null && !refreshed && tokenSource?.refresh !== undefined) {
+                refreshed = true;
+                renewed = await tokenSource.refresh(token);
+                if (renewed === null)
+                    return response;
+                await discard(response);
+                continue;
+            }
+            if ((response.status === 429 || response.status === 503) && retryable && retries < maxRetries) {
+                const wait = retryDelay(response.headers.get("Retry-After"), retries, maxWait, Date.now());
+                if (wait === null)
+                    return response;
+                await discard(response);
+                retries++;
+                await sleep(wait, request.signal);
+                continue;
+            }
+            return response;
+        }
+    };
+}
+/** Cancels the body of an answer that is not returned. */
+async function discard(response) {
+    try {
+        await response.body?.cancel();
+    }
+    catch {
+        // Nothing to release.
+    }
+}
+/**
+ * How long to wait, in milliseconds, before retry number n+1 (n from 0): what Retry-After asks for (seconds or an
+ * HTTP date), or without it an exponential backoff from one second with jitter. It is null when the wait is longer
+ * than limit.
+ */
+function retryDelay(retryAfter, n, limit, now) {
+    if (retryAfter !== null && retryAfter !== "") {
+        const ms = parseRetryAfter(retryAfter, now) ?? 1000;
+        return ms <= limit ? ms : null;
+    }
+    const base = 1000 * 2 ** Math.min(n, 10);
+    return Math.min(base + Math.random() * (base / 2), limit);
+}
+/**
+ * Reads a Retry-After header, in seconds or an HTTP date, as the wait from now in milliseconds; null when it is absent
+ * or unreadable.
+ */
+export function parseRetryAfter(retryAfter, now) {
+    const value = retryAfter?.trim() ?? "";
+    if (/^\d+$/.test(value))
+        return Number(value) * 1000;
+    if (value === "")
+        return null;
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? null : Math.max(at - now, 0);
+}
+/** Waits for ms, or rejects with the reason of signal when it aborts first. */
+export function sleepSignal(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/upload.d.ts

@@ -0,0 +1,30 @@
+import type { Api } from "./client.js";
+import type { components } from "./schema.gen.js";
+/** What the server makes of an uploaded file, which picks the sizes of its variants. */
+export type MediaUploadPurpose = components["schemas"]["MediaUpload"]["purpose"];
+/** A media file as the server describes it. */
+export type MediaAttachment = components["schemas"]["MediaAttachment"];
+/** What uploadMedia uploads. */
+export type MediaUploadInput = {
+    /** The image, video, or audio file. Its type is the part's Content-Type, which the server checks against the content. */
+    file: Blob;
+    /** The file name, such as "photo.jpg"; the name of a File, or "file", by default. */
+    fileName?: string;
+    /** The poster of a video or audio file. */
+    thumbnail?: Blob;
+    /** The file name of the thumbnail; the name of a File, or "thumbnail", by default. */
+    thumbnailName?: string;
+    /** The alternative text. */
+    description?: string;
+    /** What the file is for; attachment by default. */
+    purpose?: MediaUploadPurpose;
+};
+/**
+ * Uploads a media file (uploadMedia) as multipart/form-data. The answer is the file in its current state, usually
+ * processing: poll `GET /media/{id}` until it is ready or failed. A Blob can be read again, so the upload is sent
+ * again after a 401 like any other request; it is not retried after a 429 or 503, as POST /media takes no
+ * Idempotency-Key.
+ */
+export declare function uploadMedia(api: Api, input: MediaUploadInput, init?: {
+    signal?: AbortSignal;
+}): Promise<MediaAttachment>;

package/dist/upload.js

@@ -0,0 +1,30 @@
+function nameOf(blob, name, fallback) {
+    if (name !== undefined)
+        return name;
+    return typeof File !== "undefined" && blob instanceof File && blob.name !== "" ? blob.name : fallback;
+}
+/**
+ * Uploads a media file (uploadMedia) as multipart/form-data. The answer is the file in its current state, usually
+ * processing: poll `GET /media/{id}` until it is ready or failed. A Blob can be read again, so the upload is sent
+ * again after a 401 like any other request; it is not retried after a 429 or 503, as POST /media takes no
+ * Idempotency-Key.
+ */
+export async function uploadMedia(api, input, init) {
+    const form = new FormData();
+    form.append("file", input.file, nameOf(input.file, input.fileName, "file"));
+    if (input.thumbnail !== undefined)
+        form.append("thumbnail", input.thumbnail, nameOf(input.thumbnail, input.thumbnailName, "thumbnail"));
+    if (input.description !== undefined && input.description !== "")
+        form.append("description", input.description);
+    if (input.purpose !== undefined)
+        form.append("purpose", input.purpose);
+    const { data } = await api.POST("/media", {
+        // The body sent is the FormData of bodySerializer; the typed body only satisfies the spec's shape.
+        body: { file: "", purpose: input.purpose ?? "attachment" },
+        bodySerializer: () => form,
+        ...(init?.signal === undefined ? {} : { signal: init.signal }),
+    });
+    if (data === undefined)
+        throw new Error("mykit: uploadMedia: the answer has no body");
+    return data;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@mycroblog/mykit",
+  "version": "0.0.0-placeholder.0",
+  "description": "The client of the mycroblog/my client API: typed requests, tokens, errors, paging, and retries",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mycroblog/my.git",
+    "directory": "pkg/mykit/ts"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@mycroblog/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.lib.json --incremental --tsBuildInfoFile node_modules/.cache/tsc/tsconfig.lib.tsbuildinfo && tsc -p tsconfig.test.json --incremental --tsBuildInfoFile node_modules/.cache/tsc/tsconfig.test.tsbuildinfo && tsc -p tsconfig.examples.json --incremental --tsBuildInfoFile node_modules/.cache/tsc/tsconfig.examples.tsbuildinfo",
+    "lint": "oxlint",
+    "test": "bun test",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "openapi-fetch": "0.17.0"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.2",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "openapi-typescript": "7.13.0",
+    "oxlint": "1.87.0",
+    "oxlint-tsgolint": "7.0.2003",
+    "typescript": "npm:@typescript/typescript6@6.0.2"
+  }
+}