@org-quicko/silo-client 1.0.0 → 1.1.0

package/dist/index.cjs

@@ -53,8 +53,6 @@ __export(exports_src, {
   Search: () => Search,
   RowStream: () => RowStream,
   RouteInventory: () => RouteInventory,
-  ResolvedEntry: () => ResolvedEntry,
-  ReservedFieldNames: () => ReservedFieldNames,
   RequestAbortedError: () => RequestAbortedError,
   RenameReport: () => RenameReport,
   Projects: () => Projects,
@@ -90,8 +88,6 @@ __export(exports_src, {
   EntryReader: () => EntryReader,
   EntryPageStream: () => EntryPageStream,
   EntryPage: () => EntryPage,
-  EntryBase: () => EntryBase,
-  Entry: () => Entry,
   ConflictError: () => ConflictError,
   Collections: () => Collections,
   CollectionSchema: () => CollectionSchema,
@@ -185,6 +181,9 @@ class ApiPath {
   static mediaAssetUsages(id) {
     return `${ApiPath.mediaAsset(id)}/usages`;
   }
+  static mediaAssetContent(id) {
+    return `${ApiPath.mediaAsset(id)}/content`;
+  }
   static mediaBulkDelete() {
     return "/api/media/delete";
   }
@@ -231,6 +230,22 @@ class MediaAssetMapper {
   }
 }
 
+// src/media/media-file.ts
+class MediaFile {
+  static toBlob(bytes, contentType) {
+    if (bytes instanceof Blob)
+      return bytes;
+    return new Blob([bytes], contentType ? { type: contentType } : undefined);
+  }
+  static nameOf(input, explicit) {
+    if (explicit)
+      return explicit;
+    if (input instanceof File && input.name)
+      return input.name;
+    throw new Error("media: a Blob has no filename — pass { filename } explicitly");
+  }
+}
+
 // src/media/media-reference.ts
 class MediaReference {
   static Scheme = "silo://media/";
@@ -392,6 +407,22 @@ class MediaAsset {
   async setTags(tags, options) {
     return this.patch({ tags: [...tags] }, options);
   }
+  async replace(input, options) {
+    const form = new FormData;
+    if (input instanceof Blob) {
+      form.set("file", input, MediaFile.nameOf(input, options?.filename));
+    } else {
+      form.set("file", MediaFile.toBlob(input.bytes, input.contentType), input.filename);
+    }
+    const payload = await this.transport.upload({
+      method: "POST",
+      path: ApiPath.mediaAssetContent(this.id),
+      signal: options?.signal,
+      timeoutMilliseconds: options?.timeoutMilliseconds
+    }, form);
+    this.record = MediaAssetMapper.toRecord(payload);
+    return this;
+  }
   async delete(options) {
     await this.transport.empty({
       method: "DELETE",
@@ -625,11 +656,11 @@ class Media {
     let options;
     if (input instanceof Blob) {
       const fileOptions = second ?? {};
-      form.set("file", input, Media.filenameOf(input, fileOptions.filename));
+      form.set("file", input, MediaFile.nameOf(input, fileOptions.filename));
       folder = fileOptions.folder;
       options = third ?? fileOptions;
     } else {
-      form.set("file", Media.toBlob(input.bytes, input.contentType), input.filename);
+      form.set("file", MediaFile.toBlob(input.bytes, input.contentType), input.filename);
       folder = input.folder;
       options = second;
     }
@@ -697,18 +728,6 @@ class Media {
       sort: query.sort
     };
   }
-  static toBlob(bytes, contentType) {
-    if (bytes instanceof Blob)
-      return bytes;
-    return new Blob([bytes], contentType ? { type: contentType } : undefined);
-  }
-  static filenameOf(input, explicit) {
-    if (explicit)
-      return explicit;
-    if (input instanceof File && input.name)
-      return input.name;
-    throw new Error("media upload: a Blob has no filename — pass { filename } explicitly");
-  }
 }
 
 // src/variables/variable.ts
@@ -779,96 +798,6 @@ class ProjectVariables {
   }
 }
 
-// src/entries/entry-mapper.ts
-class EntryMapper {
-  static fieldsOf(payload) {
-    const { id: _id, rev: _rev, created_at: _createdAt, updated_at: _updatedAt, ...fields } = payload;
-    return fields;
-  }
-  static toPayload(id, rev, fields, createdAt, updatedAt) {
-    return {
-      id,
-      rev,
-      ...fields,
-      created_at: createdAt.toISOString(),
-      updated_at: updatedAt.toISOString()
-    };
-  }
-}
-
-// src/entries/entry-base.ts
-class EntryBase {
-  context;
-  id;
-  rev;
-  createdAt;
-  updatedAt;
-  fields;
-  constructor(context, payload) {
-    this.context = context;
-    this.id = String(payload.id);
-    this.rev = Number(payload.rev);
-    this.createdAt = new Date(payload.created_at);
-    this.updatedAt = new Date(payload.updated_at);
-    this.fields = EntryMapper.fieldsOf(payload);
-  }
-  toJSON() {
-    return EntryMapper.toPayload(this.id, this.rev, this.fields, this.createdAt, this.updatedAt);
-  }
-  async delete(options = {}) {
-    await this.context.transport.empty({
-      method: "DELETE",
-      path: ApiPath.entry(this.context.project, this.context.environment, this.context.collection, this.id),
-      query: { rev: this.rev },
-      ...options
-    });
-  }
-}
-
-// src/entries/resolved-entry.ts
-class ResolvedEntry extends EntryBase {
-}
-
-// src/entries/entry.ts
-class Entry extends ResolvedEntry {
-  saving = false;
-  async save(options = {}) {
-    if (this.saving) {
-      throw new Error(`cannot save entry "${this.id}": a previous save() on this instance has not finished yet`);
-    }
-    this.saving = true;
-    try {
-      const payload = await this.context.transport.json({
-        method: "PUT",
-        path: ApiPath.entry(this.context.project, this.context.environment, this.context.collection, this.id),
-        query: { rev: this.rev, variables: "raw" },
-        body: this.fields,
-        ...options
-      });
-      this.adopt(payload);
-      return this;
-    } finally {
-      this.saving = false;
-    }
-  }
-  async refresh(options = {}) {
-    const payload = await this.context.transport.json({
-      method: "GET",
-      path: ApiPath.entry(this.context.project, this.context.environment, this.context.collection, this.id),
-      query: { variables: "raw" },
-      ...options
-    });
-    this.adopt(payload);
-    return this;
-  }
-  adopt(payload) {
-    this.rev = Number(payload.rev);
-    this.createdAt = new Date(payload.created_at);
-    this.updatedAt = new Date(payload.updated_at);
-    this.fields = EntryMapper.fieldsOf(payload);
-  }
-}
-
 // src/transport/page-payload.ts
 class PagePayload {
   static read(body) {
@@ -929,40 +858,39 @@ class EntryStream extends RowStream {
 
 // src/entries/entry-reader.ts
 class EntryReader {
-  context;
-  variables;
-  wrap;
-  constructor(context, variables, wrap) {
-    this.context = context;
-    this.variables = variables;
-    this.wrap = wrap;
-  }
-  async get(id, options = {}) {
-    const payload = await this.context.transport.json({
+  scope;
+  collection;
+  constructor(scope, collection) {
+    this.scope = scope;
+    this.collection = collection;
+  }
+  get(id, options = {}) {
+    const { variables, ...request } = options;
+    return this.scope.transport.json({
       method: "GET",
-      path: ApiPath.entry(this.context.project, this.context.environment, this.context.collection, id),
-      query: { variables: this.variables },
-      ...options
+      path: ApiPath.entry(this.scope.project, this.scope.environment, this.collection, id),
+      query: { variables },
+      ...request
     });
-    return this.wrap(payload);
   }
   async list(query = {}, options = {}) {
+    const { variables, ...request } = options;
     const loader = (window2) => this.list({ ...query, limit: window2.limit, offset: window2.offset }, options);
-    const body = await this.context.transport.json({
+    const body = await this.scope.transport.json({
       method: "GET",
-      path: ApiPath.entries(this.context.project, this.context.environment, this.context.collection),
+      path: ApiPath.entries(this.scope.project, this.scope.environment, this.collection),
       query: {
         limit: query.limit,
         offset: query.offset,
         filter: query.where?.toJSON(),
         sort: query.sort === undefined ? undefined : String(query.sort),
-        variables: this.variables
+        variables
       },
-      ...options
+      ...request
     });
     const page = PagePayload.read(body);
     const window = new PageWindow(page.limit ?? query.limit ?? 50, page.offset ?? query.offset ?? 0);
-    return new EntryPage(page.rows.map((payload) => this.wrap(payload)), page.total, window, loader);
+    return new EntryPage(page.rows, page.total, window, loader);
   }
   all(query = {}, options = {}) {
     const loader = async (window) => {
@@ -1136,15 +1064,15 @@ class Search {
     const window = new PageWindow(page.limit ?? query.limit ?? 50, page.offset ?? query.offset ?? 0);
     const truncated = body.truncated === true;
     const engine = body.engine;
-    const hits = page.rows.map((hit) => this.toHit(hit));
+    const hits = page.rows.map((hit) => Search.toHit(hit));
     return new SearchPage(hits, page.total, window, truncated, engine, loader);
   }
-  toHit(payload) {
+  static toHit(payload) {
     return {
       project: payload.project,
       environment: payload.env,
       collection: payload.collection,
-      entry: new ResolvedEntry({ transport: this.transport, project: payload.project, environment: payload.env, collection: payload.collection }, payload.entry),
+      entry: payload.entry,
       snippets: payload.snippets
     };
   }
@@ -1207,36 +1135,24 @@ class CollectionHandle {
   name;
   filter = new TypedFilter;
   schema;
-  editable;
-  context;
-  resolved;
+  reader;
   constructor(scope, name) {
     this.scope = scope;
     this.name = name;
     this.schema = new CollectionSchema(scope, name);
-    this.context = {
-      transport: scope.transport,
-      project: scope.project,
-      environment: scope.environment,
-      collection: name
-    };
-    this.resolved = new EntryReader(this.context, undefined, (payload) => new ResolvedEntry(this.context, payload));
-    this.editable = new EntryReader(this.context, "raw", (payload) => new Entry(this.context, payload));
+    this.reader = new EntryReader(scope, name);
   }
   get(id, options = {}) {
-    return this.resolved.get(id, options);
-  }
-  edit(id, options = {}) {
-    return this.editable.get(id, options);
+    return this.reader.get(id, options);
   }
   list(query = {}, options = {}) {
-    return this.resolved.list(query, options);
+    return this.reader.list(query, options);
   }
   all(query = {}, options = {}) {
-    return this.resolved.all(query, options);
+    return this.reader.all(query, options);
   }
   pages(query = {}, options = {}) {
-    return this.resolved.pages(query, options);
+    return this.reader.pages(query, options);
   }
   create(fields, options = {}) {
     return this.write("POST", ApiPath.entries(this.scope.project, this.scope.environment, this.name), fields, undefined, options);
@@ -1266,23 +1182,14 @@ class CollectionHandle {
     });
     return RenameReport.fromWire(payload);
   }
-  async write(method, path, fields, rev, options) {
-    const payload = await this.scope.transport.json({
+  write(method, path, fields, rev, options) {
+    return this.scope.transport.json({
       method,
       path,
       query: { rev, variables: "raw" },
       body: fields,
       ...options
     });
-    return new Entry(this.context, payload);
-  }
-}
-
-// src/collections/reserved-field-names.ts
-class ReservedFieldNames {
-  static all = ["id", "rev", "seq", "created_at", "updated_at"];
-  static isReserved(name) {
-    return ReservedFieldNames.all.includes(name);
   }
 }
 
@@ -1301,7 +1208,6 @@ class Collections {
     return body.items.map(Collections.toSummary);
   }
   async create(name, schema, options = {}) {
-    Collections.warnOnReservedFields(schema);
     return this.scope.transport.json({
       method: "POST",
       path: ApiPath.collections(this.scope.project, this.scope.environment),
@@ -1319,13 +1225,6 @@ class Collections {
       updatedAt: new Date(payload.updated_at)
     };
   }
-  static warnOnReservedFields(schema) {
-    for (const name of Object.keys(schema.properties ?? {})) {
-      if (ReservedFieldNames.isReserved(name)) {
-        console.warn(`@org-quicko/silo-client: collection schema declares reserved field "${name}", which the server never returns`);
-      }
-    }
-  }
 }
 
 // src/variables/environment-variables.ts
@@ -1692,12 +1591,19 @@ class NetworkError extends Error {
   method;
   path;
   constructor(method, path, cause) {
-    super(`network error on ${method} ${path}: the request never reached the server`, { cause });
+    super(`network error on ${method} ${path}: the request never reached the server${NetworkError.reason(cause)}`, { cause });
     this.name = "NetworkError";
     this.method = method;
     this.path = path;
     Object.setPrototypeOf(this, NetworkError.prototype);
   }
+  static reason(cause) {
+    if (cause instanceof Error && cause.message)
+      return ` (${cause.message})`;
+    if (typeof cause === "string" && cause)
+      return ` (${cause})`;
+    return "";
+  }
 }
 
 // src/errors/timeout-error.ts
@@ -1811,7 +1717,7 @@ class Transport {
     this.key = options.key;
     this.headers = options.headers ?? {};
     this.timeoutMilliseconds = options.timeoutMilliseconds;
-    this.fetchFunction = options.fetch ?? fetch;
+    this.fetchFunction = Transport.resolveFetch(options.fetch);
   }
   async json(request) {
     const response = await this.execute(request);
@@ -1847,9 +1753,10 @@ class Transport {
   async execute(request, form) {
     const abortSignals = new AbortSignals(request.signal, request.timeoutMilliseconds ?? this.timeoutMilliseconds);
     const url = `${this.url}${request.path}${QueryString.build(request.query)}`;
+    const sendRequest = this.fetchFunction;
     let response;
     try {
-      response = await this.fetchFunction(url, {
+      response = await sendRequest(url, {
         method: request.method,
         headers: this.buildHeaders(request, Boolean(form)),
         body: form ?? (request.body === undefined ? undefined : JSON.stringify(request.body)),
@@ -1887,6 +1794,14 @@ class Transport {
   static normalizeUrl(url) {
     return url.replace(/\/+$/, "");
   }
+  static resolveFetch(fetchFunction) {
+    if (fetchFunction)
+      return fetchFunction;
+    if (typeof globalThis.fetch !== "function") {
+      throw new Error("this runtime has no global fetch: pass one as SiloOptions.fetch");
+    }
+    return globalThis.fetch.bind(globalThis);
+  }
 }
 
 // src/silo.ts
@@ -1971,6 +1886,7 @@ class RouteInventory {
     "PATCH /api/media/:id",
     "DELETE /api/media/:id",
     "GET /api/media/:id/usages",
+    "POST /api/media/:id/content",
     "POST /api/media/delete",
     "GET /api/media/folders",
     "POST /api/media/folders",
@@ -1981,6 +1897,7 @@ class RouteInventory {
     "GET /api/session": "key introspection, an operator surface",
     "GET /api/keys": "keys and claims are an operator surface",
     "POST /api/keys": "keys and claims are an operator surface",
+    "PATCH /api/keys/:id": "keys and claims are an operator surface",
     "DELETE /api/keys/:id": "keys and claims are an operator surface",
     "GET /api/audit": "an operator surface",
     "GET /api/observability": "an operator surface",

package/dist/index.d.cts

@@ -21,19 +21,17 @@ export type { DeleteOptions } from "./scope/delete-options.cjs";
 export { Collections } from "./collections/collections.cjs";
 export { CollectionHandle } from "./collections/collection-handle.cjs";
 export { CollectionSchema } from "./collections/collection-schema.cjs";
-export { ReservedFieldNames } from "./collections/reserved-field-names.cjs";
 export type { CollectionSummary } from "./collections/collection-summary.cjs";
 export type { CollectionDefinition } from "./collections/collection-definition.cjs";
 export type { JsonSchema } from "./collections/json-schema.cjs";
-export { EntryBase } from "./entries/entry-base.cjs";
-export { ResolvedEntry } from "./entries/resolved-entry.cjs";
-export { Entry } from "./entries/entry.cjs";
 export { EntryPage } from "./entries/entry-page.cjs";
 export { EntryStream } from "./entries/entry-stream.cjs";
 export { EntryPageStream } from "./entries/entry-page-stream.cjs";
 export { EntryReader } from "./entries/entry-reader.cjs";
+export type { Entry } from "./entries/entry.cjs";
+export type { EntryEnvelope } from "./entries/entry-envelope.cjs";
 export type { EntryListQuery } from "./entries/entry-list-query.cjs";
-export type { EntryPayload } from "./entries/entry-payload.cjs";
+export type { EntryReadOptions } from "./entries/entry-read-options.cjs";
 export { Filter } from "./query/filter.cjs";
 export { TypedFilter } from "./query/typed-filter.cjs";
 export { FilterField } from "./query/filter-field.cjs";
@@ -73,6 +71,7 @@ export type { MediaAssetRecord } from "./media/media-asset.cjs";
 export type { MediaQuery } from "./media/media-query.cjs";
 export type { MediaUsage } from "./media/media-usage.cjs";
 export type { MediaUsageQuery } from "./media/media-usage-page.cjs";
+export type { MediaReplace, MediaReplaceBytes, MediaReplaceOptions } from "./media/media-replace.cjs";
 export type { MediaUpload, MediaUploadBytes, MediaUploadFileOptions } from "./media/media-upload.cjs";
 export type { MediaDeleteFailure } from "./media/media-delete-failure.cjs";
 export type { MediaDeleteOptions } from "./media/media-delete-options.cjs";

package/dist/index.d.ts

@@ -21,19 +21,17 @@ export type { DeleteOptions } from "./scope/delete-options.js";
 export { Collections } from "./collections/collections.js";
 export { CollectionHandle } from "./collections/collection-handle.js";
 export { CollectionSchema } from "./collections/collection-schema.js";
-export { ReservedFieldNames } from "./collections/reserved-field-names.js";
 export type { CollectionSummary } from "./collections/collection-summary.js";
 export type { CollectionDefinition } from "./collections/collection-definition.js";
 export type { JsonSchema } from "./collections/json-schema.js";
-export { EntryBase } from "./entries/entry-base.js";
-export { ResolvedEntry } from "./entries/resolved-entry.js";
-export { Entry } from "./entries/entry.js";
 export { EntryPage } from "./entries/entry-page.js";
 export { EntryStream } from "./entries/entry-stream.js";
 export { EntryPageStream } from "./entries/entry-page-stream.js";
 export { EntryReader } from "./entries/entry-reader.js";
+export type { Entry } from "./entries/entry.js";
+export type { EntryEnvelope } from "./entries/entry-envelope.js";
 export type { EntryListQuery } from "./entries/entry-list-query.js";
-export type { EntryPayload } from "./entries/entry-payload.js";
+export type { EntryReadOptions } from "./entries/entry-read-options.js";
 export { Filter } from "./query/filter.js";
 export { TypedFilter } from "./query/typed-filter.js";
 export { FilterField } from "./query/filter-field.js";
@@ -73,6 +71,7 @@ export type { MediaAssetRecord } from "./media/media-asset.js";
 export type { MediaQuery } from "./media/media-query.js";
 export type { MediaUsage } from "./media/media-usage.js";
 export type { MediaUsageQuery } from "./media/media-usage-page.js";
+export type { MediaReplace, MediaReplaceBytes, MediaReplaceOptions } from "./media/media-replace.js";
 export type { MediaUpload, MediaUploadBytes, MediaUploadFileOptions } from "./media/media-upload.js";
 export type { MediaDeleteFailure } from "./media/media-delete-failure.js";
 export type { MediaDeleteOptions } from "./media/media-delete-options.js";