@terrascale/sdk 0.0.7 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrascale/sdk",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "JavaScript SDK, typed with JSDoc, for project-scoped C# TerraBase v1 and hosted TerraScale identity.",
   "type": "module",
   "license": "Apache-2.0",
@@ -83,6 +83,7 @@
     "!types/integration",
     "sdk-v1-route-manifest.json",
     "sdk-public-v1-route-manifest.json",
+    "sdk-file-storage-route-manifest.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/sdk-file-storage-route-manifest.json

@@ -0,0 +1,146 @@
+{
+  "producerRevision": "1c94fe262795ea87f55248989e04f5b93f2f40bf",
+  "routes": [
+    {
+      "operation": "createFileBucket",
+      "method": "POST",
+      "pathTemplate": "/v1/projects/{project}/buckets",
+      "permission": "documents:write",
+      "requestMediaTypes": [
+        "application/json"
+      ],
+      "successStatuses": [
+        201
+      ],
+      "responseMediaType": "application/json",
+      "idempotencyKey": "none",
+      "replaySafe": false,
+      "contract": "docs/file-buckets.md",
+      "contractText": []
+    },
+    {
+      "operation": "listFileBuckets",
+      "method": "GET",
+      "pathTemplate": "/v1/projects/{project}/buckets",
+      "permission": "documents:read",
+      "requestMediaTypes": [],
+      "successStatuses": [
+        200
+      ],
+      "responseMediaType": "application/json",
+      "idempotencyKey": "none",
+      "replaySafe": true,
+      "contract": "docs/file-buckets.md",
+      "contractText": []
+    },
+    {
+      "operation": "setFileBucketRules",
+      "method": "PUT",
+      "pathTemplate": "/v1/projects/{project}/buckets/{bucket}/rules",
+      "permission": "documents:write",
+      "requestMediaTypes": [
+        "application/json"
+      ],
+      "successStatuses": [
+        200
+      ],
+      "responseMediaType": "application/json",
+      "idempotencyKey": "none",
+      "replaySafe": false,
+      "contract": "docs/file-buckets.md",
+      "contractText": []
+    },
+    {
+      "operation": "deleteFileBucket",
+      "method": "DELETE",
+      "pathTemplate": "/v1/projects/{project}/buckets/{bucket}",
+      "permission": "documents:write",
+      "requestMediaTypes": [],
+      "successStatuses": [
+        204
+      ],
+      "responseMediaType": "",
+      "idempotencyKey": "none",
+      "replaySafe": false,
+      "contract": "docs/file-buckets.md",
+      "contractText": []
+    },
+    {
+      "operation": "createFileUpload",
+      "method": "POST",
+      "pathTemplate": "/v1/projects/{project}/buckets/{bucket}/files/upload",
+      "permission": "documents:write",
+      "requestMediaTypes": [
+        "application/json"
+      ],
+      "successStatuses": [
+        201
+      ],
+      "responseMediaType": "application/json",
+      "idempotencyKey": "none",
+      "replaySafe": false,
+      "contract": "docs/file-buckets.md",
+      "contractText": []
+    },
+    {
+      "operation": "completeFileUpload",
+      "method": "POST",
+      "pathTemplate": "/v1/projects/{project}/buckets/{bucket}/files/{file}/complete",
+      "permission": "documents:write",
+      "requestMediaTypes": [],
+      "successStatuses": [
+        200
+      ],
+      "responseMediaType": "application/json",
+      "idempotencyKey": "none",
+      "replaySafe": false,
+      "contract": "docs/file-buckets.md",
+      "contractText": []
+    },
+    {
+      "operation": "listBucketFiles",
+      "method": "GET",
+      "pathTemplate": "/v1/projects/{project}/buckets/{bucket}/files",
+      "permission": "documents:read",
+      "requestMediaTypes": [],
+      "successStatuses": [
+        200
+      ],
+      "responseMediaType": "application/json",
+      "idempotencyKey": "none",
+      "replaySafe": true,
+      "contract": "docs/file-buckets.md",
+      "contractText": []
+    },
+    {
+      "operation": "createFileDownload",
+      "method": "POST",
+      "pathTemplate": "/v1/projects/{project}/buckets/{bucket}/files/{file}/download",
+      "permission": "documents:read",
+      "requestMediaTypes": [],
+      "successStatuses": [
+        200
+      ],
+      "responseMediaType": "application/json",
+      "idempotencyKey": "none",
+      "replaySafe": false,
+      "contract": "docs/file-buckets.md",
+      "contractText": []
+    },
+    {
+      "operation": "deleteBucketFile",
+      "method": "DELETE",
+      "pathTemplate": "/v1/projects/{project}/buckets/{bucket}/files/{file}",
+      "permission": "documents:write",
+      "requestMediaTypes": [],
+      "successStatuses": [
+        204
+      ],
+      "responseMediaType": "",
+      "idempotencyKey": "none",
+      "replaySafe": false,
+      "contract": "docs/file-buckets.md",
+      "contractText": []
+    }
+  ]
+}

package/src/index.js

@@ -161,3 +161,13 @@ export { createTerraBaseSystemClient, V1Health, V1Platform } from "./v1/system.j
 /** @typedef {import("./v1/shape-manifest.js").V1ShapeManifestRequest} V1ShapeManifestRequest */
 /** @typedef {import("./v1/shape-reader.js").V1ShapeKeyRequest} V1ShapeKeyRequest */
 /** @typedef {import("./v1/shape-reader.js").V1ShapeKey} V1ShapeKey */
+
+export { V1FileStorage, V1FileBucket } from "./v1/file-storage.js";
+/** @typedef {import("./v1/file-storage.js").FileAccessPolicy} FileAccessPolicy */
+/** @typedef {import("./v1/file-storage.js").FileAccessRules} FileAccessRules */
+/** @typedef {import("./v1/file-storage.js").FileBucketInfo} FileBucketInfo */
+/** @typedef {import("./v1/file-storage.js").StoredFile} StoredFile */
+/** @typedef {import("./v1/file-storage.js").SignedFileUrl} SignedFileUrl */
+/** @typedef {import("./v1/file-storage.js").FileUploadRequest} FileUploadRequest */
+/** @typedef {import("./v1/file-storage.js").FileUploadOptions} FileUploadOptions */
+/** @typedef {import("./v1/file-storage.js").FileListOptions} FileListOptions */

package/src/v1/file-storage-routes.js

@@ -0,0 +1,17 @@
+/** @typedef {"createFileBucket" | "listFileBuckets" | "setFileBucketRules" | "deleteFileBucket" | "createFileUpload" | "completeFileUpload" | "listBucketFiles" | "createFileDownload" | "deleteBucketFile"} FileStorageOperation */
+const buckets = "/v1/projects/{project}/buckets";
+const bucket = `${buckets}/{bucket}`;
+const files = `${bucket}/files`;
+const file = `${files}/{file}`;
+/** @type {readonly import("./routes.js").V1Route[]} */
+export const fileStorageRoutes = Object.freeze(/** @type {import("./routes.js").V1Route[]} */ ([
+  { operation: "createFileBucket", method: "POST", pathTemplate: buckets, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [201] },
+  { operation: "listFileBuckets", method: "GET", pathTemplate: buckets, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "setFileBucketRules", method: "PUT", pathTemplate: `${bucket}/rules`, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [200] },
+  { operation: "deleteFileBucket", method: "DELETE", pathTemplate: bucket, permission: "documents:write", requestMediaTypes: [], successStatuses: [204] },
+  { operation: "createFileUpload", method: "POST", pathTemplate: `${files}/upload`, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [201] },
+  { operation: "completeFileUpload", method: "POST", pathTemplate: `${file}/complete`, permission: "documents:write", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "listBucketFiles", method: "GET", pathTemplate: files, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "createFileDownload", method: "POST", pathTemplate: `${file}/download`, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "deleteBucketFile", method: "DELETE", pathTemplate: file, permission: "documents:write", requestMediaTypes: [], successStatuses: [204] },
+].map(route => Object.freeze({ ...route, responseMediaType: route.successStatuses.includes(204) ? "" : "application/json", idempotencyKey: "none", replaySafe: route.method === "GET", contract: "docs/file-buckets.md", contractText: [] }))));

package/src/v1/file-storage.js

@@ -0,0 +1,163 @@
+import { array, boolean, malformed, object, string } from "./decode.js";
+import { requireId } from "../ids.js";
+import { assertJsonObject, stringifyExactJson } from "./json.js";
+import { requireServiceUrl } from "./transport.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { FetchLike } from "../config.js" */
+/** @import { JsonObject, JsonValue } from "./json.js" */
+/** @typedef {{ owner: boolean, public: boolean, roles: readonly string[] }} FileAccessPolicy */
+/** @typedef {{ owner: string | null, read: FileAccessPolicy, write: FileAccessPolicy }} FileAccessRules */
+/** @typedef {{ id: string, name: string, region: string, rules: FileAccessRules }} FileBucketInfo */
+/** @typedef {{ id: string, name: string, contentType: string, size: number, sha256: string, metadata: JsonObject, status: string, uploadExpiresAt: string }} StoredFile */
+/** @typedef {{ id: string, url: string, expiresAt: string, headers: Readonly<Record<string, string>> }} SignedFileUrl */
+/** @typedef {{ name: string, contentType: string, size: number, sha256: string, metadata: JsonObject }} FileUploadRequest */
+/** @typedef {{ signal?: AbortSignal | undefined }} FileRequestOptions */
+/** @typedef {{ after?: string | undefined, signal?: AbortSignal | undefined }} FileListOptions */
+/** @typedef {{ metadata: JsonObject, contentType?: string | undefined, signal?: AbortSignal | undefined }} FileUploadOptions */
+const maxFileBytes = 100 * 1024 * 1024;
+
+/** @param {JsonValue | undefined} value @returns {FileAccessPolicy} */
+function policy(value) {
+  const v = object(value, "file access policy");
+  return { owner: boolean(v.owner, "owner grant"), public: boolean(v.public, "public grant"), roles: array(v.roles, "roles").map(v => string(v, "role")) };
+}
+/** @param {JsonValue | undefined} value @returns {FileAccessRules} */
+function rules(value) {
+  const v = object(value, "file access rules");
+  return { owner: v.owner === null ? null : string(v.owner, "owner pointer"), read: policy(v.read), write: policy(v.write) };
+}
+/** @param {JsonValue | undefined} value @returns {FileBucketInfo} */
+function bucketInfo(value) {
+  const v = object(value, "file bucket");
+  return { id: requireId(v.id), name: string(v.name, "bucket name"), region: string(v.region, "bucket region"), rules: rules(v.rules) };
+}
+/** @param {JsonValue | undefined} value @returns {StoredFile} */
+function storedFile(value) {
+  const v = object(value, "file");
+  if (typeof v.size !== "number" || !Number.isSafeInteger(v.size) || v.size < 1 || v.size > maxFileBytes) malformed("file size");
+  return { id: requireId(v.id), name: string(v.name, "file name"), contentType: string(v.contentType, "content type"), size: v.size,
+    sha256: string(v.sha256, "checksum"), metadata: object(v.metadata, "file metadata"), status: string(v.status, "file status"), uploadExpiresAt: string(v.uploadExpiresAt, "upload expiry") };
+}
+/** @param {JsonValue | undefined} value @returns {SignedFileUrl} */
+function signed(value) {
+  const v = object(value, "signed file URL");
+  const url = string(v.url, "signed URL");
+  requireServiceUrl(url, "Signed file URL");
+  /** @type {Record<string, string>} */
+  const headers = {};
+  for (const [key, val] of Object.entries(object(v.headers, "signed headers"))) {
+    // Object-store capabilities must never carry the project's authorization or cookies.
+    if (!["content-type", "content-length", "x-amz-checksum-sha256"].includes(key.toLowerCase())) malformed("signed upload header");
+    headers[key] = string(val, "signed header value");
+  }
+  return { id: requireId(v.id), url, expiresAt: string(v.expiresAt, "signed URL expiry"), headers };
+}
+/** @param {FileListOptions} options @returns {URLSearchParams} */
+function pageQuery(options) {
+  const query = new URLSearchParams();
+  if (options.after !== undefined) query.set("after", requireId(options.after));
+  return query;
+}
+
+/** Project file buckets, authenticated by the same token as documents. */
+export class V1FileStorage {
+  /** @type {V1Transport} */ #transport;
+  /** @type {FetchLike} */ #fetch;
+  /** @param {V1Transport} transport @param {FetchLike} fetcher */
+  constructor(transport, fetcher) { this.#transport = transport; this.#fetch = fetcher; Object.freeze(this); }
+  /** @param {string} name @param {FileAccessRules} accessRules @param {FileRequestOptions} [options] @returns {Promise<FileBucketInfo>} */
+  async createBucket(name, accessRules, options = {}) {
+    return bucketInfo((await this.#transport.call("createFileBucket", {}, { body: stringifyExactJson({ name, rules: accessRules }, "file bucket"), contentType: "application/json", signal: options.signal })).value);
+  }
+  /** @param {FileListOptions} [options] @returns {Promise<{items: FileBucketInfo[], next: string | null}>} */
+  async listBuckets(options = {}) {
+    const v = object((await this.#transport.call("listFileBuckets", {}, { query: pageQuery(options), signal: options.signal })).value, "bucket page");
+    return { items: array(v.items, "bucket items").map(bucketInfo), next: v.next === null ? null : requireId(v.next) };
+  }
+  /** @param {string} id @returns {V1FileBucket} */
+  bucket(id) { return new V1FileBucket(this.#transport, this.#fetch, requireId(id)); }
+}
+
+/** Immutable files in one project bucket. */
+export class V1FileBucket {
+  /** @type {V1Transport} */ #transport;
+  /** @type {FetchLike} */ #fetch;
+  /** @type {string} */ #bucket;
+  /** @param {V1Transport} transport @param {FetchLike} fetcher @param {string} bucket */
+  constructor(transport, fetcher, bucket) { this.#transport = transport; this.#fetch = fetcher; this.#bucket = requireId(bucket); Object.freeze(this); }
+  /** @param {FileAccessRules} accessRules @param {FileRequestOptions} [options] @returns {Promise<FileBucketInfo>} */
+  async setRules(accessRules, options = {}) {
+    return bucketInfo((await this.#transport.call("setFileBucketRules", { bucket: this.#bucket }, { body: stringifyExactJson({ rules: accessRules }, "file bucket rules"), contentType: "application/json", signal: options.signal })).value);
+  }
+  /** @param {FileRequestOptions} [options] @returns {Promise<void>} */
+  async delete(options = {}) { await this.#transport.call("deleteFileBucket", { bucket: this.#bucket }, { signal: options.signal }); }
+  /** @param {FileUploadRequest} request @param {FileRequestOptions} [options] @returns {Promise<SignedFileUrl>} */
+  async createUpload(request, options = {}) {
+    assertJsonObject(request.metadata, "file metadata");
+    if (!Number.isSafeInteger(request.size) || request.size < 1 || request.size > maxFileBytes) throw new TypeError("Files must contain 1–104857600 bytes.");
+    return signed((await this.#transport.call("createFileUpload", { bucket: this.#bucket }, { body: stringifyExactJson(request, "file upload"), contentType: "application/json", signal: options.signal })).value);
+  }
+  /** @param {string} id @param {FileRequestOptions} [options] @returns {Promise<StoredFile>} */
+  async completeUpload(id, options = {}) {
+    return storedFile((await this.#transport.call("completeFileUpload", { bucket: this.#bucket, file: requireId(id) }, { signal: options.signal })).value);
+  }
+  /** @param {FileListOptions} [options] @returns {Promise<{items: StoredFile[], next: string | null}>} */
+  async list(options = {}) {
+    const v = object((await this.#transport.call("listBucketFiles", { bucket: this.#bucket }, { query: pageQuery(options), signal: options.signal })).value, "file page");
+    return { items: array(v.items, "file items").map(storedFile), next: v.next === null ? null : requireId(v.next) };
+  }
+  /** @param {string} id @param {FileRequestOptions} [options] @returns {Promise<SignedFileUrl>} */
+  async downloadUrl(id, options = {}) {
+    return signed((await this.#transport.call("createFileDownload", { bucket: this.#bucket, file: requireId(id) }, { signal: options.signal })).value);
+  }
+  /** @param {string} id @param {FileRequestOptions} [options] @returns {Promise<void>} */
+  async deleteFile(id, options = {}) { await this.#transport.call("deleteBucketFile", { bucket: this.#bucket, file: requireId(id) }, { signal: options.signal }); }
+  /** Hashes a private byte snapshot, uploads it without project credentials, and verifies completion. No retries.
+   * @param {string} name @param {Uint8Array | Blob} input @param {FileUploadOptions} options @returns {Promise<StoredFile>} */
+  async upload(name, input, options) {
+    const size = input instanceof Blob ? input.size : input.byteLength;
+    if (size < 1 || size > maxFileBytes) throw new TypeError("Files must contain 1–104857600 bytes.");
+    const bytes = input instanceof Blob ? new Uint8Array(await input.arrayBuffer()) : new Uint8Array(input);
+    options.signal?.throwIfAborted();
+    const hash = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes));
+    const sha256 = btoa(String.fromCharCode(...hash));
+    const capability = await this.createUpload({ name, contentType: options.contentType ?? "application/octet-stream", size, sha256, metadata: options.metadata }, options);
+    const headers = new Headers(capability.headers);
+    // Fetch computes Content-Length from the body; browsers prohibit setting it explicitly.
+    headers.delete("Content-Length");
+    /** @type {RequestInit & { duplex?: "half" }} */
+    const init = { method: "PUT", headers, body: bytes, credentials: "omit", redirect: "error", signal: options.signal ?? null };
+    if (typeof process !== "undefined" && process.release?.name === "node") {
+      // A one-shot stream prevents Node fetch from replaying the signed PUT on HTTP 421.
+      headers.set("Content-Length", String(size));
+      init.body = new ReadableStream({ start(controller) { controller.enqueue(bytes); controller.close(); } });
+      init.duplex = "half";
+    }
+    const response = await this.#fetch(capability.url, init);
+    void response.body?.cancel().catch(() => {});
+    if (!response.ok) throw new Error(`Object upload failed (${response.status}).`);
+    return this.completeUpload(capability.id, options);
+  }
+  /** Fetches file bytes without sending the project token to the object store.
+   * @param {string} id @param {FileRequestOptions} [options] @returns {Promise<Blob>} */
+  async download(id, options = {}) {
+    const capability = await this.downloadUrl(id, options);
+    const response = await this.#fetch(capability.url, { method: "GET", credentials: "omit", redirect: "error", signal: options.signal ?? null });
+    if (!response.ok) throw new Error(`Object download failed (${response.status}).`);
+    if (response.body === null) throw new Error("Object download returned no body.");
+    const reader = response.body.getReader();
+    /** @type {Uint8Array<ArrayBuffer>[]} */ const chunks = [];
+    let length = 0;
+    try {
+      for (;;) {
+        options.signal?.throwIfAborted();
+        const part = await reader.read();
+        if (part.done) break;
+        length += part.value.byteLength;
+        if (length > maxFileBytes) throw new Error("Object download exceeds the file size limit.");
+        chunks.push(new Uint8Array(part.value));
+      }
+    } finally { await reader.cancel().catch(() => {}); reader.releaseLock(); }
+    return new Blob(chunks, { type: "application/octet-stream" });
+  }
+}

package/src/v1/routes.js

@@ -1,6 +1,7 @@
+import { fileStorageRoutes } from "./file-storage-routes.js";
 import { managementV1Routes } from "./management-routes.js";
 // Current TerraBase routes at e30ffdc; readShape is retained from release 6cb9745 only.
-/** @typedef {import("./management-routes.js").ManagementOperation | "readFreeShape" | "getShapeKey" | "getDocument" | "putDocument" | "createDocument" | "patchDocument" | "deleteDocument" | "commitTransaction" | "queryDocuments" | "createCollection" | "getCollection" | "listCollections" | "dropCollection" | "readShape" | "runSql" | "checkSql" | "explainSql" | "streamDatabaseChanges" | "listDocuments" | "getCollectionSchema" | "putCollectionSchema" | "deleteCollectionSchema" | "createDatabase" | "listDatabases" | "getDatabase" | "updateDatabase" | "deleteDatabase" | "branchDatabase"} V1Operation */
+/** @typedef {import("./file-storage-routes.js").FileStorageOperation | import("./management-routes.js").ManagementOperation | "readFreeShape" | "getShapeKey" | "getDocument" | "putDocument" | "createDocument" | "patchDocument" | "deleteDocument" | "commitTransaction" | "queryDocuments" | "createCollection" | "getCollection" | "listCollections" | "dropCollection" | "readShape" | "runSql" | "checkSql" | "explainSql" | "streamDatabaseChanges" | "listDocuments" | "getCollectionSchema" | "putCollectionSchema" | "deleteCollectionSchema" | "createDatabase" | "listDatabases" | "getDatabase" | "updateDatabase" | "deleteDatabase" | "branchDatabase"} V1Operation */
 /**
  * @typedef {object} V1Route
  * @property {V1Operation} operation
@@ -61,7 +62,7 @@ export const v1Routes = Object.freeze(/** @type {V1Route[]} */ ([
 })));
 /** @param {V1Operation} operation @returns {V1Route} */
 export function v1Route(operation) {
-  const route = [...v1Routes, ...shapeV1Routes, ...managementV1Routes].find(candidate => candidate.operation === operation);
+  const route = [...v1Routes, ...shapeV1Routes, ...managementV1Routes, ...fileStorageRoutes].find(candidate => candidate.operation === operation);
   if (route === undefined) throw new TypeError(`Unknown v1 operation ${operation}.`);
   return route;
 }

package/src/v1/terrabase-v1.js

@@ -1,3 +1,4 @@
+import { V1FileStorage } from "./file-storage.js";
 // The TerraBase v1 client: documents, transactions, queries and shapes over
 // the project-scoped C# Documents API (decision 0004 and shape-reads.md).
 import {
@@ -1003,6 +1004,8 @@ export class V1Database {
  * privately; it is never serialized, logged or forwarded to redirects.
  */
 export class TerraBaseV1Client {
+  /** @type {V1FileStorage} */
+  #storage;
   /** @type {V1Health} */
   #health;
   /** @type {V1Platform} */
@@ -1022,6 +1025,7 @@ export class TerraBaseV1Client {
   constructor(config) {
     requireId(config.project);
     this.#transport = new V1Transport(config);
+    this.#storage = new V1FileStorage(this.#transport, config.fetch ?? globalThis.fetch.bind(globalThis));
     this.#databases = new V1Databases(this.#transport);
     this.#savedQueries = new V1SavedQueries(this.#transport);
     this.#metrics = new V1ProjectUsageClient(this.#transport);
@@ -1041,6 +1045,8 @@ export class TerraBaseV1Client {
 
   /** @returns {V1Databases} Project-scoped database catalog. */
   get databases() { return this.#databases; }
+  /** @returns {V1FileStorage} Project file buckets. */
+  get storage() { return this.#storage; }
   /** @returns {V1SavedQueries} */
   get savedQueries() { return this.#savedQueries; }
   /** @returns {V1ProjectUsageClient} */

package/src/v1/usage.js

@@ -8,7 +8,7 @@ const period = record({ from: text, to: text, granularity: text, reads: numeric,
 const series = list(record({ start: text, reads: numeric, writes: numeric }));
 const databaseUsage = record({ databaseId: requireId, storageBytes: numeric, logicalBytes: numeric, collections: numeric,
   documents: numeric, reads: numeric, writes: numeric, period, series });
-const projectUsage = record({ projectId: requireId, databases: numeric, storageBytes: numeric, logicalBytes: numeric,
+const projectUsage = record({ projectId: requireId, databases: numeric, storageBytes: numeric, logicalBytes: numeric, fileBytes: numeric,
   documents: numeric, reads: numeric, writes: numeric, period, series, items: list(databaseUsage) });
 const bandwidth = record({ bytesSent: numeric, bytesReceived: numeric });
 const directedBandwidth = list(record({ sourceRegion: text, destinationRegion: text, kind: text, bytesSent: numeric, bytesReceived: numeric }));

package/types/index.d.ts

@@ -128,6 +128,14 @@ export type V1ShapeManifest = import("./v1/shape-manifest.js").V1ShapeManifest;
 export type V1ShapeManifestRequest = import("./v1/shape-manifest.js").V1ShapeManifestRequest;
 export type V1ShapeKeyRequest = import("./v1/shape-reader.js").V1ShapeKeyRequest;
 export type V1ShapeKey = import("./v1/shape-reader.js").V1ShapeKey;
+export type FileAccessPolicy = import("./v1/file-storage.js").FileAccessPolicy;
+export type FileAccessRules = import("./v1/file-storage.js").FileAccessRules;
+export type FileBucketInfo = import("./v1/file-storage.js").FileBucketInfo;
+export type StoredFile = import("./v1/file-storage.js").StoredFile;
+export type SignedFileUrl = import("./v1/file-storage.js").SignedFileUrl;
+export type FileUploadRequest = import("./v1/file-storage.js").FileUploadRequest;
+export type FileUploadOptions = import("./v1/file-storage.js").FileUploadOptions;
+export type FileListOptions = import("./v1/file-storage.js").FileListOptions;
 export { createTerraBaseV1Client as createTerraBaseClient, TerraBaseV1Client as TerraBaseClient, createTerraBaseV1Client, TerraBaseV1Client, V1Database, V1Collection, V1Collections, V1Transaction } from "./v1/terrabase-v1.js";
 export { terraScaleReleaseBlockers, TerraScaleCapabilityUnavailableError } from "./management-contracts.js";
 export { TerraBaseV1Error, V1PreconditionFailedError, V1InvalidKeyError, V1ForbiddenScopeError, V1NotFoundError, SqlError, V1ErrorCode, isTerraBaseV1Error } from "./v1/errors.js";
@@ -135,3 +143,4 @@ export { generateId, isValidId, requireId } from "./ids.js";
 export { V1ProjectUsageClient, V1DatabaseUsageClient } from "./v1/usage.js";
 export { V1Backups, V1BackupDestinationClient } from "./v1/backups.js";
 export { createTerraBaseSystemClient, V1Health, V1Platform } from "./v1/system.js";
+export { V1FileStorage, V1FileBucket } from "./v1/file-storage.js";

package/types/v1/file-storage-routes.d.ts

@@ -0,0 +1,3 @@
+/** @type {readonly import("./routes.js").V1Route[]} */
+export const fileStorageRoutes: readonly import("./routes.js").V1Route[];
+export type FileStorageOperation = "createFileBucket" | "listFileBuckets" | "setFileBucketRules" | "deleteFileBucket" | "createFileUpload" | "completeFileUpload" | "listBucketFiles" | "createFileDownload" | "deleteBucketFile";

package/types/v1/file-storage.d.ts

@@ -0,0 +1,98 @@
+/** Project file buckets, authenticated by the same token as documents. */
+export class V1FileStorage {
+    /** @param {V1Transport} transport @param {FetchLike} fetcher */
+    constructor(transport: V1Transport, fetcher: FetchLike);
+    /** @param {string} name @param {FileAccessRules} accessRules @param {FileRequestOptions} [options] @returns {Promise<FileBucketInfo>} */
+    createBucket(name: string, accessRules: FileAccessRules, options?: FileRequestOptions): Promise<FileBucketInfo>;
+    /** @param {FileListOptions} [options] @returns {Promise<{items: FileBucketInfo[], next: string | null}>} */
+    listBuckets(options?: FileListOptions): Promise<{
+        items: FileBucketInfo[];
+        next: string | null;
+    }>;
+    /** @param {string} id @returns {V1FileBucket} */
+    bucket(id: string): V1FileBucket;
+    #private;
+}
+/** Immutable files in one project bucket. */
+export class V1FileBucket {
+    /** @param {V1Transport} transport @param {FetchLike} fetcher @param {string} bucket */
+    constructor(transport: V1Transport, fetcher: FetchLike, bucket: string);
+    /** @param {FileAccessRules} accessRules @param {FileRequestOptions} [options] @returns {Promise<FileBucketInfo>} */
+    setRules(accessRules: FileAccessRules, options?: FileRequestOptions): Promise<FileBucketInfo>;
+    /** @param {FileRequestOptions} [options] @returns {Promise<void>} */
+    delete(options?: FileRequestOptions): Promise<void>;
+    /** @param {FileUploadRequest} request @param {FileRequestOptions} [options] @returns {Promise<SignedFileUrl>} */
+    createUpload(request: FileUploadRequest, options?: FileRequestOptions): Promise<SignedFileUrl>;
+    /** @param {string} id @param {FileRequestOptions} [options] @returns {Promise<StoredFile>} */
+    completeUpload(id: string, options?: FileRequestOptions): Promise<StoredFile>;
+    /** @param {FileListOptions} [options] @returns {Promise<{items: StoredFile[], next: string | null}>} */
+    list(options?: FileListOptions): Promise<{
+        items: StoredFile[];
+        next: string | null;
+    }>;
+    /** @param {string} id @param {FileRequestOptions} [options] @returns {Promise<SignedFileUrl>} */
+    downloadUrl(id: string, options?: FileRequestOptions): Promise<SignedFileUrl>;
+    /** @param {string} id @param {FileRequestOptions} [options] @returns {Promise<void>} */
+    deleteFile(id: string, options?: FileRequestOptions): Promise<void>;
+    /** Hashes a private byte snapshot, uploads it without project credentials, and verifies completion. No retries.
+     * @param {string} name @param {Uint8Array | Blob} input @param {FileUploadOptions} options @returns {Promise<StoredFile>} */
+    upload(name: string, input: Uint8Array | Blob, options: FileUploadOptions): Promise<StoredFile>;
+    /** Fetches file bytes without sending the project token to the object store.
+     * @param {string} id @param {FileRequestOptions} [options] @returns {Promise<Blob>} */
+    download(id: string, options?: FileRequestOptions): Promise<Blob>;
+    #private;
+}
+export type FileAccessPolicy = {
+    owner: boolean;
+    public: boolean;
+    roles: readonly string[];
+};
+export type FileAccessRules = {
+    owner: string | null;
+    read: FileAccessPolicy;
+    write: FileAccessPolicy;
+};
+export type FileBucketInfo = {
+    id: string;
+    name: string;
+    region: string;
+    rules: FileAccessRules;
+};
+export type StoredFile = {
+    id: string;
+    name: string;
+    contentType: string;
+    size: number;
+    sha256: string;
+    metadata: JsonObject;
+    status: string;
+    uploadExpiresAt: string;
+};
+export type SignedFileUrl = {
+    id: string;
+    url: string;
+    expiresAt: string;
+    headers: Readonly<Record<string, string>>;
+};
+export type FileUploadRequest = {
+    name: string;
+    contentType: string;
+    size: number;
+    sha256: string;
+    metadata: JsonObject;
+};
+export type FileRequestOptions = {
+    signal?: AbortSignal | undefined;
+};
+export type FileListOptions = {
+    after?: string | undefined;
+    signal?: AbortSignal | undefined;
+};
+export type FileUploadOptions = {
+    metadata: JsonObject;
+    contentType?: string | undefined;
+    signal?: AbortSignal | undefined;
+};
+import type { V1Transport } from "./transport.js";
+import type { FetchLike } from "../config.js";
+import type { JsonObject } from "./json.js";

package/types/v1/routes.d.ts

@@ -6,7 +6,7 @@ export function v1RoutePath(route: V1Route, params: Readonly<Record<string, stri
 export const v1Routes: readonly V1Route[];
 /** @type {readonly V1Route[]} */
 export const shapeV1Routes: readonly V1Route[];
-export type V1Operation = import("./management-routes.js").ManagementOperation | "readFreeShape" | "getShapeKey" | "getDocument" | "putDocument" | "createDocument" | "patchDocument" | "deleteDocument" | "commitTransaction" | "queryDocuments" | "createCollection" | "getCollection" | "listCollections" | "dropCollection" | "readShape" | "runSql" | "checkSql" | "explainSql" | "streamDatabaseChanges" | "listDocuments" | "getCollectionSchema" | "putCollectionSchema" | "deleteCollectionSchema" | "createDatabase" | "listDatabases" | "getDatabase" | "updateDatabase" | "deleteDatabase" | "branchDatabase";
+export type V1Operation = import("./file-storage-routes.js").FileStorageOperation | import("./management-routes.js").ManagementOperation | "readFreeShape" | "getShapeKey" | "getDocument" | "putDocument" | "createDocument" | "patchDocument" | "deleteDocument" | "commitTransaction" | "queryDocuments" | "createCollection" | "getCollection" | "listCollections" | "dropCollection" | "readShape" | "runSql" | "checkSql" | "explainSql" | "streamDatabaseChanges" | "listDocuments" | "getCollectionSchema" | "putCollectionSchema" | "deleteCollectionSchema" | "createDatabase" | "listDatabases" | "getDatabase" | "updateDatabase" | "deleteDatabase" | "branchDatabase";
 export type V1Route = {
     operation: V1Operation;
     method: "GET" | "PUT" | "POST" | "PATCH" | "DELETE";

package/types/v1/terrabase-v1.d.ts

@@ -341,6 +341,8 @@ export class TerraBaseV1Client {
     database(name: string): V1Database;
     /** @returns {V1Databases} Project-scoped database catalog. */
     get databases(): V1Databases;
+    /** @returns {V1FileStorage} Project file buckets. */
+    get storage(): V1FileStorage;
     /** @returns {V1SavedQueries} */
     get savedQueries(): V1SavedQueries;
     /** @returns {V1ProjectUsageClient} */
@@ -592,6 +594,7 @@ import { V1DatabaseUsageClient } from "./usage.js";
 import { V1Indexes } from "./indexes.js";
 import { V1DatabaseSchemaClient } from "./database-schema.js";
 import { V1Databases } from "./catalog.js";
+import { V1FileStorage } from "./file-storage.js";
 import { V1SavedQueries } from "./saved-queries.js";
 import { V1ProjectUsageClient } from "./usage.js";
 import { V1BackupDestinationClient } from "./backups.js";

package/types/v1/usage.d.ts

@@ -63,6 +63,7 @@ declare const projectUsage: import("./management-decode.js").Decoder<Readonly<{
     databases: number | import("./json.js").ExactDecimal;
     storageBytes: number | import("./json.js").ExactDecimal;
     logicalBytes: number | import("./json.js").ExactDecimal;
+    fileBytes: number | import("./json.js").ExactDecimal;
     documents: number | import("./json.js").ExactDecimal;
     reads: number | import("./json.js").ExactDecimal;
     writes: number | import("./json.js").ExactDecimal;