@omelhorsite/sdk 0.1.0 → 0.2.0

package/README.md

@@ -89,6 +89,7 @@ const rows = await oms.http.get<{ id: string }[]>("/some/new/path");
 | `oms.account` | The signed-in user, their profile, their usage report. |
 | `oms.storage` | The virtual filesystem: nodes, uploads, downloads, grants. |
 | `oms.tools` | The metered media tools, each with its own daily quota. |
+| `oms.quotas` | Every ceiling on the account - tools, storage and music - in one call. |
 | `oms.jobs` | Background jobs: list, get, wait, watch. The API has no cancel. |
 | `oms.tickets` | Support tickets and their message threads. |
 | `oms.shortLinks` `oms.notepads` `oms.dynamicQrs` `oms.chests` `oms.forms` `oms.linkTrees` | Everything that ends in a shareable URL. |

package/dist/index.js

@@ -322,6 +322,7 @@ class ApiClient {
   baseUrl;
   fetchImpl;
   tokens;
+  sessionCookie;
   baseHeaders;
   timeoutMs;
   retry;
@@ -332,7 +333,11 @@ class ApiClient {
       throw new OmsNetworkError("No fetch implementation available. Pass one to the Oms constructor: new Oms({ fetch }).");
     }
     this.fetchImpl = (input, init) => injected(input, init);
+    if (options.sessionCookie && options.tokens) {
+      throw new TypeError("Pass either `sessionCookie` or a token, not both: two credentials on one request means the server decides which identity wins, and the caller cannot tell which one it got.");
+    }
     this.tokens = options.tokens;
+    this.sessionCookie = options.sessionCookie ?? false;
     this.baseHeaders = { ...options.headers ?? {} };
     if (options.clientName)
       this.baseHeaders["X-Oms-Client"] = options.clientName;
@@ -451,7 +456,7 @@ class ApiClient {
       headers,
       signal,
       ...body === undefined ? {} : { body },
-      credentials: "omit",
+      credentials: this.sessionCookie ? "include" : "omit",
       redirect: "follow"
     };
   }
@@ -10476,6 +10481,45 @@ class NotepadsNamespace extends Resource {
   }
 }
 
+// src/resources/quotas.ts
+var QUOTA_RESOURCES = [
+  "vocal_separation_seconds",
+  "transcription_seconds",
+  "caption_seconds",
+  "jumpstyle_edits",
+  "storage_nodes",
+  "music_storage_bytes"
+];
+
+class QuotasNamespace extends Resource {
+  async list(options = {}) {
+    const answer = await this.http.get("/quotas", options);
+    return {
+      authenticated: answer?.authenticated === true,
+      quotas: answer?.quotas ?? []
+    };
+  }
+  async get(resource, options = {}) {
+    return quotaFor(await this.list(options), resource) ?? null;
+  }
+}
+function quotaFor(report, resource) {
+  return report.quotas.find((entry) => entry.resource === resource);
+}
+function quotaExhausted(entry) {
+  if (entry.unlimited || entry.remaining === null)
+    return false;
+  return entry.remaining <= 0;
+}
+function quotaAffords(entry, amount) {
+  if (entry.unlimited)
+    return true;
+  const remaining = entry.remaining ?? (entry.limit === null ? null : Math.max(0, entry.limit - entry.used));
+  if (remaining === null)
+    return true;
+  return amount <= remaining;
+}
+
 // src/resources/storage.ts
 class FsGrantsNamespace extends Resource {
   async list(params = {}, options = {}) {
@@ -11389,17 +11433,22 @@ class Oms {
   forms;
   linkTrees;
   jobs;
+  quotas;
   tools;
   local = local;
   constructor(options = {}) {
     if (options.tokens && options.token !== undefined && options.token !== null) {
       throw new TypeError("Pass either `token` or `tokens` to the Oms constructor, not both.");
     }
+    if (options.sessionCookie && (options.tokens || options.token !== undefined && options.token !== null)) {
+      throw new TypeError("Pass either `sessionCookie` or a token to the Oms constructor, not both.");
+    }
     const tokens2 = options.tokens ?? providerFor(options.token);
     this.http = new ApiClient({
       ...options.baseUrl === undefined ? {} : { baseUrl: options.baseUrl },
       ...options.fetch === undefined ? {} : { fetch: options.fetch },
       ...tokens2 === undefined ? {} : { tokens: tokens2 },
+      ...options.sessionCookie === undefined ? {} : { sessionCookie: options.sessionCookie },
       ...options.headers === undefined ? {} : { headers: options.headers },
       ...options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs },
       ...options.retry === undefined ? {} : { retry: options.retry },
@@ -11417,6 +11466,7 @@ class Oms {
     this.forms = new FormsNamespace(this.http);
     this.linkTrees = new LinkTreesNamespace(this.http);
     this.jobs = new JobsNamespace(this.http);
+    this.quotas = new QuotasNamespace(this.http);
     this.tools = new ToolsNamespace(this.http);
   }
   get baseUrl() {
@@ -11459,6 +11509,9 @@ export {
   readFileInput,
   readErrorBody,
   randomInt,
+  quotaFor,
+  quotaExhausted,
+  quotaAffords,
   qrToSvg,
   qrToDataUri,
   pollUntilTerminal,
@@ -11524,6 +11577,8 @@ export {
   ShortLinksNamespace,
   SHORT_LINK_BASE_URL,
   Resource,
+  QuotasNamespace,
+  QUOTA_RESOURCES,
   POLL_BACKOFF_FACTOR,
   PART_URL_WINDOW,
   OmsTimeoutError,

package/dist/types/client.d.ts

@@ -21,6 +21,7 @@ import { IpLookupNamespace } from "./resources/ipLookup";
 import { JobsNamespace } from "./resources/jobs";
 import { LinkTreesNamespace } from "./resources/linkTrees";
 import { NotepadsNamespace } from "./resources/notepads";
+import { QuotasNamespace } from "./resources/quotas";
 import { ShortLinksNamespace } from "./resources/shortLinks";
 import { StorageNamespace } from "./resources/storage";
 import { TicketsNamespace } from "./resources/tickets";
@@ -48,6 +49,18 @@ export interface OmsOptions {
      * passing both throws. Build one with `refreshingTokenProvider`.
      */
     readonly tokens?: TokenProvider;
+    /**
+     * Authenticate with the browser's httpOnly session cookie instead of a
+     * token. First-party pages only, and never the default: see
+     * {@link ApiClientOptions.sessionCookie} for why it has to be asked for
+     * by name.
+     *
+     * ```ts
+     * // in the omelhorsite web app, served from the same site as the API
+     * const oms = new Oms({ sessionCookie: true });
+     * ```
+     */
+    readonly sessionCookie?: boolean;
     /** API root. Defaults to `https://backend.omelhorsite.pt`. */
     readonly baseUrl?: string;
     /**
@@ -110,6 +123,8 @@ export declare class Oms {
     readonly linkTrees: LinkTreesNamespace;
     /** Background jobs: listing, polling and watching. There is no cancel. */
     readonly jobs: JobsNamespace;
+    /** Every ceiling on the account - tools, storage and music - in one call. */
+    readonly quotas: QuotasNamespace;
     /** The metered media tools, each with its own daily quota. */
     readonly tools: ToolsNamespace;
     /**

package/dist/types/http.d.ts

@@ -40,6 +40,23 @@ export interface ApiClientOptions {
     readonly fetch?: FetchLike;
     /** Where the bearer token comes from. */
     readonly tokens?: TokenProvider;
+    /**
+     * Authenticate with the browser's `oms_session` cookie instead of a token.
+     *
+     * FOR A FIRST-PARTY PAGE ONLY, and never the default. The cookie is httpOnly
+     * precisely so that no JavaScript can read the session token; a page served
+     * from omelhorsite.pt asks the browser to attach it, and the token itself
+     * stays out of reach of any script on the page.
+     *
+     * That is also why this has to be asked for by name. Left off, an SDK call is
+     * authenticated by the token it was handed and by nothing else, so a page
+     * that embeds the SDK cannot act as whoever happens to be signed in. Turning
+     * it on is a statement that this code IS the first-party app.
+     *
+     * Requires a same-site page: the cookie is host-only on the API host, so a
+     * page anywhere else gets an unauthenticated request, not an error.
+     */
+    readonly sessionCookie?: boolean;
     /** Headers merged into every request, below per-call headers. */
     readonly headers?: Record<string, string>;
     /** Default deadline for one call, retries included. `0` disables it. */
@@ -85,6 +102,7 @@ export declare class ApiClient {
     readonly baseUrl: string;
     private readonly fetchImpl;
     private readonly tokens;
+    private readonly sessionCookie;
     private readonly baseHeaders;
     private readonly timeoutMs;
     private readonly retry;

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

@@ -126,9 +126,12 @@ export interface AccountStorageUsage {
 /**
  * `GET /account/usage`: what the account has spent, per area.
  *
- * This is a bespoke report, not the daily tool quotas - each metered tool
- * reports its own ceiling through its `quota()` call. There is also a row
- * ceiling (250 000 nodes) that this report does not carry.
+ * This is a bespoke report, not a quota answer: it carries breakdowns nothing
+ * else has (the biggest files, the extension histogram) and it does NOT carry
+ * every ceiling - the row ceiling on the file tree and the music byte ceiling
+ * are absent from it. For ceilings, ask `oms.quotas.list()`, which answers all
+ * of them in one call; each metered tool also still reports its own through
+ * its `quota()`.
  */
 export interface AccountUsage {
     readonly user: {

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

@@ -23,6 +23,7 @@ export * from "./ipLookup";
 export * from "./jobs";
 export * from "./linkTrees";
 export * from "./notepads";
+export * from "./quotas";
 export * from "./shortLinks";
 export * from "./storage";
 export * from "./storage/upload";

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

@@ -0,0 +1,122 @@
+/**
+ * The `quotas` namespace: every ceiling on the account, in one call.
+ *
+ * This exists because the question an agent actually asks is "how much is left
+ * of everything", and answering it used to mean knowing which four tools were
+ * metered, calling four endpoints, and then knowing that neither storage nor
+ * music was in any of those answers. `oms.quotas.list()` is one request and
+ * returns every resource the server meters, each in the same shape.
+ *
+ * The per-tool `quota()` calls have NOT gone anywhere and answer exactly what
+ * they always answered - they are published API. Use them when you want one
+ * tool and nothing else, or when the credential carries `tools:read` but not
+ * `profile`; use this when you want the picture.
+ *
+ * Two things to read before trusting a number:
+ *
+ * - **`period` is not decoration.** A `"daily"` resource resets at midnight,
+ *   server time, and `used` is what today has spent. A `"total"` resource is
+ *   what is stored RIGHT NOW and only falls when something is deleted; waiting
+ *   does not give it back.
+ * - **Anonymous callers get a shorter list.** Without a credential the server
+ *   answers with the daily resources only, counted per IP, because an
+ *   anonymous caller has no file tree and no music library. Never index the
+ *   array by position - look the resource up by name, or use
+ *   {@link quotaFor}, which returns `undefined` rather than lying.
+ *
+ * Needs the `profile` scope for an OAuth token, the same scope
+ * `account.usage()` needs, because a quota is account state and it spans tools,
+ * storage and music at once.
+ *
+ * ```ts
+ * const report = await oms.quotas.list();
+ * const music = quotaFor(report, "music_storage_bytes");
+ * if (music && !quotaAffords(music, file.size)) throw new Error("no room");
+ * ```
+ */
+import { Resource } from "../http";
+import type { RequestOptions } from "../types";
+/**
+ * Every resource the server's catalogue defines today, in the order it answers
+ * them: the four metered tools first, then the two storage ceilings.
+ *
+ * A server that grows a seventh keeps working - {@link QuotaEntry.resource} is
+ * widened to `string` on purpose, so an unknown name arrives as data rather
+ * than as a type error in a client nobody has rebuilt.
+ */
+export declare const QUOTA_RESOURCES: readonly ["vocal_separation_seconds", "transcription_seconds", "caption_seconds", "jumpstyle_edits", "storage_nodes", "music_storage_bytes"];
+/** One of {@link QUOTA_RESOURCES}. */
+export type QuotaResource = (typeof QUOTA_RESOURCES)[number];
+/**
+ * What the numbers count. `"seconds"` of media, `"count"` of whole things
+ * (edits, files and folders), `"bytes"` of stored media.
+ */
+export type QuotaUnit = "seconds" | "count" | "bytes";
+/**
+ * `"daily"` spends and resets at midnight, server time. `"total"` is what is
+ * stored right now and only falls when something is deleted.
+ */
+export type QuotaPeriod = "daily" | "total";
+/** One resource, in the one shape every resource uses. */
+export interface QuotaEntry {
+    /** A {@link QuotaResource}, or a name added to the server since this build. */
+    readonly resource: QuotaResource | string;
+    readonly unit: QuotaUnit | string;
+    readonly period: QuotaPeriod | string;
+    /** Spent today for a daily resource; stored right now for a total one. */
+    readonly used: number;
+    /** `null` exactly when {@link unlimited} is `true`. */
+    readonly limit: number | null;
+    /** `null` exactly when {@link unlimited} is `true`. Never negative. */
+    readonly remaining: number | null;
+    /** `true` when this account has no ceiling on this resource. */
+    readonly unlimited: boolean;
+}
+/** `GET /quotas` in full. */
+export interface QuotaReport {
+    /** Whether the caller was recognised. Anonymous callers get a shorter list. */
+    readonly authenticated: boolean;
+    /** One entry per resource the caller can actually spend. */
+    readonly quotas: QuotaEntry[];
+}
+/** The `quotas` namespace, reachable as `oms.quotas`. */
+export declare class QuotasNamespace extends Resource {
+    /**
+     * `GET /quotas` - every ceiling on the account, in one request.
+     *
+     * Works anonymously, and then answers with the daily resources only.
+     *
+     * Every number is computed on the spot - the daily ones are aggregates over
+     * today's rows, and the two totals are a subtree row count and a blob-size
+     * sum - so this is a call to make BEFORE an expensive upload, not one to
+     * poll. The server throttles it at thirty a minute per caller, well above
+     * that use and well below a loop.
+     */
+    list(options?: RequestOptions): Promise<QuotaReport>;
+    /**
+     * One resource, or `null` when the caller cannot spend it - which is what an
+     * anonymous caller gets for `storage_nodes` and `music_storage_bytes`.
+     *
+     * Costs the same single request as {@link list}, because the server has no
+     * per-resource endpoint. Asking for three resources means calling
+     * {@link list} once and using {@link quotaFor} three times, not calling this
+     * three times.
+     */
+    get(resource: QuotaResource | string, options?: RequestOptions): Promise<QuotaEntry | null>;
+}
+/**
+ * Finds one resource in a report. Returns `undefined` when it is not there,
+ * which is a real answer and not a failure: an anonymous caller has no storage
+ * quota because they have no storage.
+ */
+export declare function quotaFor(report: QuotaReport, resource: QuotaResource | string): QuotaEntry | undefined;
+/** True when there is nothing left to spend. Always false when unlimited. */
+export declare function quotaExhausted(entry: QuotaEntry): boolean;
+/**
+ * Whether `amount` more fits under the ceiling, in the resource's own unit.
+ *
+ * Always true when unlimited. Uses `remaining` when the server sent one and
+ * falls back to `limit - used` when it did not, so it is honest about a report
+ * that is missing a field rather than reading `null` as zero.
+ */
+export declare function quotaAffords(entry: QuotaEntry, amount: number): boolean;

package/dist/types/resources/tools/index.d.ts

@@ -9,7 +9,9 @@
  * - it is asynchronous: the create call answers with a row in `"pending"` and
  *   the work happens on a sidecar;
  * - it has a daily quota, metered in seconds for the audio and video tools and
- *   in edits for jumpstyle, and smaller for an anonymous caller;
+ *   in edits for jumpstyle, and smaller for an anonymous caller - each tool's
+ *   own `quota()` reads it, and `oms.quotas.list()` reads all of them plus the
+ *   storage ceilings in one request;
  * - an anonymous caller must pass a Turnstile token
  *   ({@link ToolCaptcha.captchaToken}, sent as `cf_turnstile_token`).
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omelhorsite/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript SDK for the omelhorsite API. Isolate-safe: no node builtins, no environment access, no stdout.",
   "type": "module",
   "license": "UNLICENSED",
@@ -17,11 +17,12 @@
     "dist"
   ],
   "scripts": {
-    "typecheck": "tsc --noEmit -p .",
+    "typecheck": "tsc --noEmit -p . && tsc --noEmit -p tsconfig.test.json",
     "check:isolate": "bun run scripts/check-isolate.ts",
     "test": "bun run check:isolate && bun test",
     "build": "bun build src/index.ts --target node --format esm --outdir dist --external uqr && tsc -p tsconfig.build.json",
-    "prepublishOnly": "bun run build"
+    "prepublishOnly": "bun run build",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.test.json"
   },
   "devDependencies": {
     "typescript": "^5.9.3"
@@ -31,7 +32,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/afonsopc/omelhorsite.git",
-    "directory": "apps/cli/packages/core"
+    "url": "git+https://github.com/afonsopc/omelhorsite-sdk.git"
   }
 }