@omelhorsite/sdk 0.1.0

package/dist/types/resources/chests.d.ts

@@ -0,0 +1,194 @@
+/**
+ * The `chests` namespace: short-lived drop boxes for moving files and text
+ * between two devices that share nothing else.
+ *
+ * Two secrets, and they are not the same thing:
+ * - the chest NAME is the read capability. Anyone holding it opens the chest
+ *   and lists its entries. It is the slug in the shareable link.
+ * - the chest TOKEN is the owner capability, and it is handed out ONCE, in the
+ *   201 that created the chest. Lose it and, unless the creator was signed in,
+ *   the chest can never be managed again.
+ *
+ * Chests expire two hours after creation, so any read can legitimately 404 on
+ * something that existed a minute ago. Creating one anonymously is throttled
+ * to five an hour per IP and gated by a captcha.
+ */
+import { type ApiClient, Resource } from "../http";
+import type { BaseRecord, FileInput, Id, OperationOptions, RequestOptions, Timestamp } from "../types";
+/** What an entry holds: a file's bytes, or a piece of text. */
+export type ChestEntryKind = "file" | "note";
+/** A drop box. */
+export interface Chest extends BaseRecord {
+    /** Human-readable read capability. Treat it as a secret. */
+    readonly name: string;
+    /** Whether anyone holding the name may add and remove entries. */
+    readonly editable_by_others: boolean;
+    /** Ceiling in bytes: 5 GB when created anonymously, 10 GB when signed in. */
+    readonly max_size: number;
+    /** Bytes already reserved by the entries. */
+    readonly current_size: number;
+    /** When the chest and everything in it is deleted. */
+    readonly expires_at: Timestamp;
+    /** Owner, when the chest was created by a signed-in user. */
+    readonly creator_id?: Id | null;
+    /** Present on every read: `find_or_create` renders the `:extended` view. */
+    readonly chest_entries?: ChestEntry[];
+}
+/** One item inside a chest: a note, or a file. */
+export interface ChestEntry extends BaseRecord {
+    readonly chest_id: Id;
+    readonly kind: ChestEntryKind;
+    /** Display name; the filename for a file entry. */
+    readonly name: string;
+    /** Text of a note. `null` on a file entry. */
+    readonly content?: string | null;
+    /** Bytes this entry reserves against the chest's ceiling. */
+    readonly size: number;
+    /** False while a file entry exists but its bytes have not landed yet. */
+    readonly data_attached: boolean;
+}
+/** What {@link ChestsNamespace.open} answers with. */
+export interface ChestOpenResult extends Chest {
+    /** Endpoint of the `c/` short link pointing at this chest. */
+    readonly short_link_endpoint: string | null;
+    /**
+     * The owner capability. Present ONLY on the call that created the chest.
+     * Store it there and then, or lose the ability to manage this chest.
+     */
+    readonly chest_token?: string;
+    /**
+     * Whether this call minted the chest (HTTP 201) rather than finding one
+     * (HTTP 200). Derived by the SDK from the status code; the body does not
+     * say. It is also exactly when `chest_token` is present.
+     */
+    readonly created: boolean;
+}
+/** Arguments for {@link ChestsNamespace.open}. */
+export interface OpenChestInput {
+    /**
+     * Name to open. Omit it to be handed your own active chest, minting one if
+     * you have none - and that branch is what the throttle and the captcha
+     * apply to.
+     */
+    readonly name?: string;
+    /**
+     * Turnstile token. Required to MINT a chest anonymously (no `name`, no
+     * active chest of your own); ignored otherwise and never needed by a
+     * signed-in caller.
+     */
+    readonly captchaToken?: string;
+}
+/** Arguments for adding an entry to a chest. */
+export interface CreateChestEntryInput {
+    readonly chestId: Id;
+    /**
+     * The owner capability. Not needed when the chest has `editable_by_others`
+     * on, or when you are the signed-in creator.
+     */
+    readonly chestToken?: string;
+    /** Display name. Required for a note; defaults to the file's own filename. */
+    readonly name?: string;
+    /** Text to store. Mutually exclusive with `file`. */
+    readonly content?: string;
+    /** File to store. Mutually exclusive with `content`. */
+    readonly file?: FileInput;
+}
+/** Arguments for the explicit three-step file upload. */
+export interface CreateChestFileInput {
+    readonly chestId: Id;
+    readonly file: FileInput;
+    readonly chestToken?: string;
+    /** Overrides the name stored for the entry. Defaults to the filename. */
+    readonly name?: string;
+}
+/** Options for the calls that prove ownership of a chest. */
+export interface ChestOwnerOptions extends RequestOptions {
+    /** The owner capability, unless you are the signed-in creator. */
+    readonly chestToken?: string;
+}
+/** Entries of a chest, reachable as `oms.chests.entries`. */
+export declare class ChestEntriesNamespace extends Resource {
+    private readonly uploads;
+    constructor(http: ApiClient);
+    /**
+     * Adds an entry. A note is one request; a file goes through
+     * {@link createWithUpload}, because a chest never takes bytes through Rails.
+     *
+     * ```ts
+     * await oms.chests.entries.create({ chestId, name: "notes", content: "..." });
+     * await oms.chests.entries.create({ chestId, file: file(bytes, "clip.mov") });
+     * ```
+     */
+    create(input: CreateChestEntryInput, options?: OperationOptions): Promise<ChestEntry>;
+    /**
+     * Uploads a file the direct way, in four hops:
+     *
+     * 1. `POST /chest_entries` reserves the space (`kind: "file"`, `size`);
+     * 2. `POST /chest_entries/:id/attachment_signed_url` presigns a PUT;
+     * 3. the PUT goes straight to object storage, with no `Authorization`;
+     * 4. `POST /chest_entries/:id/attach_blob` binds the bytes to the entry.
+     *
+     * Step 2 may be called ONCE per entry: a second call raises an unhandled
+     * `ArgumentError` server-side and comes back as a 500, so a naive retry is
+     * worse than useless. The SDK therefore treats the whole thing as atomic -
+     * anything that fails after step 1 destroys the half-built entry (releasing
+     * the space it reserved) before rethrowing, so a retry starts clean.
+     *
+     * The file is buffered whole: the MD5 the presigned signature covers has to
+     * be computed over all of it.
+     */
+    createWithUpload(input: CreateChestFileInput, options?: OperationOptions): Promise<ChestEntry>;
+    /**
+     * `GET /chest_entries/:id/data` - the entry's bytes.
+     *
+     * Answers 302 towards object storage and `fetch` follows it. Note that this
+     * endpoint checks nothing at all: the entry id alone is enough to download
+     * it, with or without the chest name or token.
+     */
+    download(id: Id, options?: RequestOptions): Promise<Blob>;
+    /**
+     * `DELETE /chest_entries/:id` - removes an entry and gives its bytes back to
+     * the chest's ceiling.
+     *
+     * Accepts the owner token, and also accepts ANY caller when the chest has
+     * `editable_by_others` on.
+     */
+    delete(id: Id, options?: ChestOwnerOptions): Promise<void>;
+}
+/** The `chests` namespace, reachable as `oms.chests`. */
+export declare class ChestsNamespace extends Resource {
+    /** Items inside a chest. */
+    readonly entries: ChestEntriesNamespace;
+    constructor(http: ApiClient);
+    /**
+     * `GET /chests/find_or_create` - opens a chest by name, or hands you your
+     * own, minting one if you have none.
+     *
+     * Read {@link ChestOpenResult.chest_token} on the way past: when `created`
+     * is true that field is the only copy of the owner capability you will ever
+     * be given.
+     *
+     * ```ts
+     * const mine = await oms.chests.open();               // yours, or a new one
+     * const theirs = await oms.chests.open({ name });     // someone's, by name
+     * ```
+     *
+     * @throws {OmsApiError} 404 when a named chest is unknown or has expired.
+     * @throws {OmsQuotaError} 429 when the global ceiling of 30 live chests is
+     *   full, or when an anonymous caller has spent the hourly budget of five.
+     */
+    open(input?: OpenChestInput, options?: RequestOptions): Promise<ChestOpenResult>;
+    /**
+     * `PATCH /chests/:id/toggle_editable` - flips whether holders of the name
+     * may write, or only read.
+     *
+     * Turning it OFF destroys every file entry in the chest. Notes survive.
+     */
+    toggleEditable(id: Id, options?: ChestOwnerOptions): Promise<Chest>;
+    /**
+     * `DELETE /chests/:id/owner_destroy` - destroys the chest and its entries
+     * before the expiry. Owner only, proved by the token or by being the
+     * signed-in creator.
+     */
+    delete(id: Id, options?: ChestOwnerOptions): Promise<void>;
+}

package/dist/types/resources/dynamicQrs.d.ts

@@ -0,0 +1,172 @@
+/**
+ * The `dynamicQrs` namespace: QR codes whose destination can be changed after
+ * the code has been printed.
+ *
+ * Under the hood each one is a `ShortLink` in the reserved `"qr"` namespace
+ * with a server-minted UUID endpoint, plus the styling the renderer needs. It
+ * is a separate resource because the endpoint is not user-chosen, the payload
+ * carries `settings`, and the plain short-link listing filters system
+ * namespaces out - a dynamic QR will never appear in `oms.shortLinks.list()`.
+ *
+ * Rendering the image itself is a LOCAL operation with no network: encode
+ * `oms.dynamicQrs.publicUrl(qr)` with `oms.local.qr`. This namespace only
+ * manages the redirect and its statistics.
+ *
+ * Every action here requires a credential; there is no anonymous path.
+ */
+import { Resource } from "../http";
+import type { BaseRecord, Id, JsonObject, RequestOptions } from "../types";
+import { type ShortLinkId, type ShortLinkStats } from "./shortLinks";
+/** Public prefix a dynamic QR resolves under. */
+export declare const DYNAMIC_QR_BASE_URL = "https://omelhor.site/qr";
+/** Module shapes `DynamicQrs::SettingsSanitizer` accepts. Anything else is dropped. */
+export type DynamicQrStyle = "classic" | "rounded" | "dots" | "extraRounded" | "classy" | "classyRounded";
+/**
+ * Styling of a dynamic QR.
+ *
+ * The backend runs this bag through `DynamicQrs::SettingsSanitizer`, which
+ * **silently drops** every key it does not recognise and every value that fails
+ * its check - a bad `style`, a colour that is not `#rrggbb`. An unknown or
+ * malformed key is therefore a no-op, not an error, and the only way to know
+ * what stuck is to read `settings` back off the response.
+ *
+ * The two exceptions that DO fail loudly are `logo` and `bg_image`: a value
+ * that is neither `null`/`""` nor a `data:image/...` URI under the size cap is
+ * a 400.
+ *
+ * The SDK does not render any of this; it is what the web tool's renderer
+ * consumes. `oms.local.qr` draws a plain symbol from the matrix instead.
+ */
+export interface DynamicQrSettings {
+    /** Module shape. Values outside {@link DynamicQrStyle} are dropped. */
+    readonly style?: DynamicQrStyle;
+    /** Error-correction level. Higher survives a bigger logo. Dropped unless `L`/`M`/`Q`/`H`. */
+    readonly error_correction_level?: "L" | "M" | "Q" | "H";
+    /** Foreground colour, `#rrggbb` exactly (six digits, leading `#`). Dropped otherwise. */
+    readonly fg_color?: string;
+    /** Background colour, `#rrggbb` exactly. Dropped otherwise. */
+    readonly bg_color?: string;
+    /** Foreground opacity, clamped to `[0, 1]`. */
+    readonly fg_alpha?: number;
+    /** Background opacity, clamped to `[0, 1]`. */
+    readonly bg_alpha?: number;
+    /** Legacy switch kept for old saved codes; equivalent to `fg_alpha: 0`. */
+    readonly fg_transparent?: boolean;
+    /** Legacy switch kept for old saved codes; equivalent to `bg_alpha: 0`. */
+    readonly bg_transparent?: boolean;
+    /**
+     * Logo overlaid in the centre, as a `data:image/...` URI under 512 000 bytes.
+     * `null` or `""` clears it. Anything else is a 400.
+     */
+    readonly logo?: string | null;
+    /**
+     * Background image, as a `data:image/...` URI under 2 048 000 bytes. `null`
+     * or `""` clears it. Anything else is a 400.
+     */
+    readonly bg_image?: string | null;
+    /** How the background image sits against `bg_color`. Anything but `"replace"` reads as `"behind"`. */
+    readonly bg_image_mode?: "replace" | "behind";
+    /**
+     * The stored bag is free-form JSON, so a code saved by an older version of
+     * the web tool can carry keys this interface does not name.
+     */
+    readonly [key: string]: unknown;
+}
+/** A dynamic QR code. */
+export interface DynamicQr extends Omit<BaseRecord, "id"> {
+    /** Integer primary key: a dynamic QR is a `short_links` row. See {@link ShortLinkId}. */
+    readonly id: number;
+    /** Current destination. Changing it re-points every printed copy at once. */
+    readonly url: string;
+    /** Server-assigned UUID the QR image encodes. Not choosable, not renameable. */
+    readonly endpoint: string;
+    /** Always `"qr"`. */
+    readonly namespace: string;
+    readonly user_id: Id | null;
+    /** Never `null`: the blueprint substitutes `{}` for an unset bag. */
+    readonly settings: DynamicQrSettings & JsonObject;
+}
+/** Arguments for creating a dynamic QR. */
+export interface CreateDynamicQrInput {
+    /** Absolute `http`/`https` destination. Blank is a 400. */
+    readonly url: string;
+    /** Initial styling. Unrecognised keys are dropped without complaint. */
+    readonly settings?: DynamicQrSettings;
+}
+/**
+ * Fields that can change afterwards.
+ *
+ * `settings` is **merged** into the stored bag by the backend, not replaced, so
+ * an update can never unset a key by omitting it. To clear one, send it
+ * explicitly with the value that means empty (`null` for `logo`/`bg_image`).
+ */
+export interface UpdateDynamicQrInput {
+    readonly url?: string;
+    readonly settings?: DynamicQrSettings;
+}
+/** The `dynamicQrs` namespace, reachable as `oms.dynamicQrs`. */
+export declare class DynamicQrsNamespace extends Resource {
+    /**
+     * `GET /dynamic_qrs` - every code you own, newest first.
+     *
+     * Returns a plain array rather than a page object, and that is not an
+     * oversight: this controller does not use `CrudActions` and ignores
+     * `modifiers[page]` entirely, so it always answers with the complete set. A
+     * `Paginated` here would be a fiction with a `next()` that refetched
+     * everything.
+     *
+     * @throws {OmsAuthError} 401 when anonymous.
+     */
+    list(options?: RequestOptions): Promise<DynamicQr[]>;
+    /**
+     * `POST /dynamic_qrs` - mints a code and its permanent endpoint.
+     *
+     * Retries are off by default: a replayed `POST` after a 502 mints a second
+     * code with a second endpoint, and the one that got printed is decided by
+     * which response you happened to keep. Pass `retry` explicitly to override.
+     *
+     * @throws {OmsAuthError} 401 when anonymous.
+     * @throws {OmsApiError} 400 when `url` is blank or invalid, or when `logo` /
+     *   `bg_image` is not a `data:` URI within the size cap.
+     */
+    create(input: CreateDynamicQrInput, options?: RequestOptions): Promise<DynamicQr>;
+    /**
+     * `PATCH /dynamic_qrs/:id` - repoints the code or restyles it.
+     *
+     * This is the whole point of the resource: the printed symbol never changes,
+     * only where it lands. `settings` merges; see {@link UpdateDynamicQrInput}.
+     *
+     * @throws {OmsApiError} 404 when the code is not yours, 400 on a blank URL or
+     *   an oversized `logo` / `bg_image`.
+     */
+    update(id: ShortLinkId, input: UpdateDynamicQrInput, options?: RequestOptions): Promise<DynamicQr>;
+    /**
+     * `DELETE /dynamic_qrs/:id`.
+     *
+     * Every printed copy dies with it: the endpoint stops resolving and the
+     * recorded clicks are destroyed alongside the row. There is no undo and no
+     * tombstone redirect.
+     *
+     * @throws {OmsApiError} 404 when the code is not yours.
+     */
+    delete(id: ShortLinkId, options?: RequestOptions): Promise<void>;
+    /**
+     * `GET /dynamic_qrs/:id/stats` - byte-for-byte the same click summary a short
+     * link gets, including the fixed 30-day window.
+     *
+     * @throws {OmsApiError} 404 when the code is not yours.
+     */
+    stats(id: ShortLinkId, options?: RequestOptions): Promise<ShortLinkStats>;
+    /**
+     * The URL the printed symbol should encode. Pure string building, no request.
+     *
+     * Always encode THIS, never `qr.url`: the whole redirect indirection is what
+     * makes the destination editable after printing.
+     *
+     * ```ts
+     * const qr = await oms.dynamicQrs.create({ url: "https://example.com" });
+     * const svg = oms.local.qr.toSvg(oms.dynamicQrs.publicUrl(qr), { ecc: "H" });
+     * ```
+     */
+    publicUrl(qr: Pick<DynamicQr, "endpoint">): string;
+}