@protobase/client 0.21.6 → 0.21.8

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import { FilterInput, ListParams, MapParams } from "./query-string.js";
 import { ClientOptions } from "./transport.js";
 import { UploadProgress } from "./upload-request.js";
-import { Aggregate, AggregateParams, BatchOp, BatchResult, Facet, Histogram, HistoryPage, ListPage, MapResult, MetaResult, RecordOf, ResourceRef, Series, SeriesParams, Stored } from "./types.js";
+import { Aggregate, AggregateParams, BatchOp, BatchResult, CommentPage, Facet, FormChallenge, FormProof, Histogram, HistoryPage, ListPage, MapResult, MentionableUser, MetaResult, PublicForm, RecordComment, RecordOf, ResourceRef, Series, SeriesParams, Stored } from "./types.js";
 import { KeyValue } from "@protobase/schema";
 //#region src/client.d.ts
 /** How `invoke` calls a function: GET without a body, POST with one, unless `method` says otherwise. */
@@ -52,11 +52,21 @@ export declare const createClient: (options?: ClientOptions) => {
     etag?: string;
   }) => Promise<void>;
   undelete: <R extends ResourceRef>(resource: R, key: KeyValue | readonly KeyValue[]) => Promise<Stored<RecordOf<R>>>;
+  generate: <R extends ResourceRef>(resource: R, key: KeyValue | readonly KeyValue[], action: string) => Promise<Stored<RecordOf<R>>>;
   reveal: (resource: ResourceRef, key: KeyValue | readonly KeyValue[], field: string) => Promise<unknown>;
   history: (resource: ResourceRef, key: KeyValue | readonly KeyValue[], { pageSize, pageToken }?: {
     pageSize?: number;
     pageToken?: string;
   }) => Promise<HistoryPage>;
+  comments: (resource: ResourceRef, key: KeyValue | readonly KeyValue[], { pageSize, pageToken }?: {
+    pageSize?: number;
+    pageToken?: string;
+  }) => Promise<CommentPage>;
+  comment: (resource: ResourceRef, key: KeyValue | readonly KeyValue[], { body, mentions }: {
+    body: string;
+    mentions?: string[];
+  }) => Promise<RecordComment>;
+  mentionable: (resource: ResourceRef, key: KeyValue | readonly KeyValue[], query: string) => Promise<MentionableUser[]>;
   batchWrite: (ops: BatchOp[]) => Promise<BatchResult>;
   facets: (resource: ResourceRef, field: string, o?: {
     filter?: FilterInput;
@@ -80,6 +90,9 @@ export declare const createClient: (options?: ClientOptions) => {
   }) => Promise<MetaResult>;
   invoke: <T = unknown>(name: string, { method, body, path, query, headers }?: InvokeOptions) => Promise<T>;
   upload: (resource: ResourceRef, field: string, file: Blob, { onProgress, signal }?: UploadOptions) => Promise<UploadResult>;
+  form: (name: string) => Promise<PublicForm>;
+  formChallenge: (name: string) => Promise<FormChallenge>;
+  submitForm: (name: string, values: Record<string, unknown>, proof: FormProof) => Promise<void>;
 };
 export type Client = ReturnType<typeof createClient>;
 //#endregion

package/dist/client.js

@@ -16,6 +16,10 @@ const toPage = (body, response, origin) => ({
 	...body.photos !== void 0 && { photos: photosWithOrigin(body.photos, origin) },
 	...response.headers.get("x-protobase-warning") && { warning: response.headers.get("x-protobase-warning") }
 });
+const commentOf = ({ created_at, ...comment }) => ({
+	...comment,
+	createdAt: created_at
+});
 const etagOf = (response) => response.headers.get("etag") ?? "";
 /** A single-record response: the record without its `permissions` member, which travels beside it. */
 const storedOf = async (response, origin) => {
@@ -123,6 +127,15 @@ const createClient = (options = {}) => {
 			body: { field }
 		})).json()).value;
 	};
+	/**
+	* Runs the record's AI action `action` (`a.ai`): the model writes the action's field from its prompt, as the caller.
+	* Resolves to the record as written; a record changed while the model answered rejects with `PreconditionFailedError`.
+	*/
+	const generate = async (resource, key, action) => storedOf(await send({
+		method: "POST",
+		path: `${keyPath(resource, key)}:generate`,
+		body: { action }
+	}), origin);
 	/** A page of a record's changes, newest first, for a resource with `.history()`; `pageToken` is the previous page's `nextPageToken`. */
 	const history = async (resource, key, { pageSize, pageToken } = {}) => {
 		const query = queryString({
@@ -142,6 +155,39 @@ const createClient = (options = {}) => {
 			nextPageToken: body.next_page_token
 		};
 	};
+	/** A page of a record's comments, newest first, for a resource with `.comments()`; `pageToken` is the previous page's `nextPageToken`. */
+	const comments = async (resource, key, { pageSize, pageToken } = {}) => {
+		const query = queryString({
+			page_size: pageSize,
+			page_token: pageToken || void 0
+		});
+		const body = await (await send({
+			method: "GET",
+			path: `${keyPath(resource, key)}:comments`,
+			query
+		})).json();
+		return {
+			items: body.items.map(commentOf),
+			nextPageToken: body.next_page_token
+		};
+	};
+	/** Adds the caller's comment to a record, mentioning the users `mentions` names, who are emailed a link to it. */
+	const comment = async (resource, key, { body, mentions = [] }) => commentOf(await (await send({
+		method: "POST",
+		path: `${keyPath(resource, key)}:comments`,
+		body: {
+			body,
+			mentions
+		}
+	})).json());
+	/** The users a comment on a record may mention whose name contains `query`, at most 8, by name. */
+	const mentionable = async (resource, key, query) => {
+		return (await (await send({
+			method: "GET",
+			path: `${keyPath(resource, key)}:mentionable`,
+			query: queryString({ q: query })
+		})).json()).items;
+	};
 	/** Applies several writes atomically (`POST /api/v1:batchWrite`), for example a record and its lines on Save. */
 	const batchWrite = async (ops) => {
 		const keyText = (key) => typeof key === "object" && key !== null && "$ref" in key ? key : encodeKey(key);
@@ -323,6 +369,34 @@ const createClient = (options = {}) => {
 		onProgress?.(file.size, file.size);
 		return result;
 	};
+	const formPath = (name) => `/forms/${encodeURIComponent(name)}`;
+	/** The public form `name` (`GET /api/forms/<name>`): its fields as `/meta` would give them, its title and thanks text. */
+	const form = async (name) => (await send({
+		method: "GET",
+		path: formPath(name),
+		system: true
+	})).json();
+	/** A fresh bot check for the public form `name`, to solve with `altcha-lib`'s `solveChallenge` before sending it. */
+	const formChallenge = async (name) => (await send({
+		method: "GET",
+		path: `${formPath(name)}:challenge`,
+		system: true
+	})).json();
+	/**
+	* Sends the public form `name`: creates its record from `values`, with the solved bot check. Rejects with `ApiError`
+	* as a create does, a refused check as `bot-check-failed` and too many submissions as `too-many-submissions`.
+	*/
+	const submitForm = async (name, values, proof) => {
+		await send({
+			method: "POST",
+			path: formPath(name),
+			body: {
+				values,
+				proof
+			},
+			system: true
+		});
+	};
 	return {
 		list,
 		search,
@@ -331,8 +405,12 @@ const createClient = (options = {}) => {
 		update,
 		remove,
 		undelete,
+		generate,
 		reveal,
 		history,
+		comments,
+		comment,
+		mentionable,
 		batchWrite,
 		facets,
 		aggregate,
@@ -342,7 +420,10 @@ const createClient = (options = {}) => {
 		seek,
 		meta,
 		invoke,
-		upload
+		upload,
+		form,
+		formChallenge,
+		submitForm
 	};
 };
 //#endregion

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { FilterInput, ListParams, MapParams, filterText, listWire } from "./query-string.js";
 import { ClientOptions } from "./transport.js";
 import { UploadProgress } from "./upload-request.js";
-import { Aggregate, AggregateGroup, AggregateParams, BatchOp, BatchRef, BatchResult, Facet, Histogram, HistogramBucket, HistoryChange, HistoryPage, ListPage, MapBounds, MapBucket, MapLayerModel, MapResult, Meta, MetaResult, PluginRef, RecordOf, RecordPermissions, RecordPhotos, RelatedLabels, ResourcePermissions, ResourceRef, Series, SeriesParams, SeriesPoint, SourceRef, Stored, StoredFile, StoredFileVariant } from "./types.js";
+import { Aggregate, AggregateGroup, AggregateParams, BatchOp, BatchRef, BatchResult, CommentPage, CommentPerson, Facet, FormChallenge, FormProof, Histogram, HistogramBucket, HistoryChange, HistoryPage, ListPage, MapBounds, MapBucket, MapLayerModel, MapResult, MentionableUser, Meta, MetaResult, PluginRef, PublicForm, RecordComment, RecordOf, RecordPermissions, RecordPhotos, RelatedLabels, ResourcePermissions, ResourceRef, Series, SeriesParams, SeriesPoint, SourceRef, Stored, StoredFile, StoredFileVariant } from "./types.js";
 import { Client, InvokeOptions, UploadOptions, UploadResult, createClient } from "./client.js";
 import { ApiError, PreconditionFailedError, ProblemDetails, ProblemError, isApiError } from "./problem.js";
 import { fileUrl } from "./file-urls.js";
@@ -18,4 +18,4 @@ import { AuthSession, AuthSessionOptions, createAuthSession, tokenExpiry } from
 import { createStaticSession } from "./static-session.js";
 import { AssistantClient, AssistantClientOptions, AssistantConnection, createAssistantClient } from "./assistant.js";
 import { RuntimeClient, RuntimeClientOptions, RuntimeLastUpdate, RuntimePolicy, RuntimeStatus, RuntimeUpdateStage, createRuntimeClient } from "./runtime.js";
-export { type AccountSecurity, type AccountSignIn, type ActiveRole, type Aggregate, type AggregateGroup, type AggregateParams, ApiError, type AssistantClient, type AssistantClientOptions, type AssistantConnection, AuthError, type AuthSession, type AuthSessionOptions, type AuthUser, type AuthenticatorSetup, type BatchOp, type BatchRef, type BatchResult, type Client, type ClientOptions, type CurrentOrganization, type Facet, type FilterInput, type Histogram, type HistogramBucket, type HistoryChange, type HistoryPage, type InvitationPreview, type InvitationSent, type InvokeOptions, type ListPage, type ListParams, type MapBounds, type MapBucket, type MapLayerModel, type MapParams, type MapResult, type Meta, type MetaResult, type Organization, type OrganizationInvitation, type OrganizationMember, type OrganizationRole, type OrganizationsClient, type Passkey, type PlatformSignIn, type PluginRef, PreconditionFailedError, type ProblemDetails, type ProblemError, type RecordOf, type RecordPermissions, type RecordPhotos, type RelatedLabels, type RequiredSetup, type ResourcePermissions, type ResourceRef, type RoleLabel, type RoleOption, type RolesClient, type RuntimeClient, type RuntimeClientOptions, type RuntimeLastUpdate, type RuntimePolicy, type RuntimeStatus, type RuntimeUpdateStage, type Series, type SeriesParams, type SeriesPoint, type SetupStatus, type SignInMethod, type SignInPolicy, type SignInPolicyClient, type SignInPolicyState, type SignInResult, type SignInRule, type SourceMeta, type SourceRef, type StaffAccessRule, type StaffSignIn, type StaffSignInClient, type Stored, type StoredFile, type StoredFileVariant, type TwoFactorMethod, type UploadOptions, type UploadProgress, type UploadResult, createAssistantClient, createAuthSession, createClient, createRuntimeClient, createStaticSession, fileUrl, filterText, isApiError, listWire, routedClient, sourceMeta, tokenExpiry };
+export { type AccountSecurity, type AccountSignIn, type ActiveRole, type Aggregate, type AggregateGroup, type AggregateParams, ApiError, type AssistantClient, type AssistantClientOptions, type AssistantConnection, AuthError, type AuthSession, type AuthSessionOptions, type AuthUser, type AuthenticatorSetup, type BatchOp, type BatchRef, type BatchResult, type Client, type ClientOptions, type CommentPage, type CommentPerson, type CurrentOrganization, type Facet, type FilterInput, type FormChallenge, type FormProof, type Histogram, type HistogramBucket, type HistoryChange, type HistoryPage, type InvitationPreview, type InvitationSent, type InvokeOptions, type ListPage, type ListParams, type MapBounds, type MapBucket, type MapLayerModel, type MapParams, type MapResult, type MentionableUser, type Meta, type MetaResult, type Organization, type OrganizationInvitation, type OrganizationMember, type OrganizationRole, type OrganizationsClient, type Passkey, type PlatformSignIn, type PluginRef, PreconditionFailedError, type ProblemDetails, type ProblemError, type PublicForm, type RecordComment, type RecordOf, type RecordPermissions, type RecordPhotos, type RelatedLabels, type RequiredSetup, type ResourcePermissions, type ResourceRef, type RoleLabel, type RoleOption, type RolesClient, type RuntimeClient, type RuntimeClientOptions, type RuntimeLastUpdate, type RuntimePolicy, type RuntimeStatus, type RuntimeUpdateStage, type Series, type SeriesParams, type SeriesPoint, type SetupStatus, type SignInMethod, type SignInPolicy, type SignInPolicyClient, type SignInPolicyState, type SignInResult, type SignInRule, type SourceMeta, type SourceRef, type StaffAccessRule, type StaffSignIn, type StaffSignInClient, type Stored, type StoredFile, type StoredFileVariant, type TwoFactorMethod, type UploadOptions, type UploadProgress, type UploadResult, createAssistantClient, createAuthSession, createClient, createRuntimeClient, createStaticSession, fileUrl, filterText, isApiError, listWire, routedClient, sourceMeta, tokenExpiry };

package/dist/routed-client.d.ts

@@ -2,8 +2,8 @@ import { Client } from "./client.js";
 //#region src/routed-client.d.ts
 /**
  * One client over the app's own API and the sources it draws resources from: a call about a resource goes to the API
- * that serves it (`sourceOf` gives a source's client, or `undefined` for the app's own), and `meta` and `invoke` go to
- * the app's own. A batch goes to the one API all its writes are for; one that writes to two cannot be atomic, so it is
+ * that serves it (`sourceOf` gives a source's client, or `undefined` for the app's own), and `meta`, `invoke` and the
+ * public forms go to the app's own. A batch goes to the one API all its writes are for; one that writes to two cannot be atomic, so it is
  * refused before anything is sent.
  */
 export declare const routedClient: (own: Client, sourceOf: (resource: string) => Client | undefined) => Client;

package/dist/routed-client.js

@@ -2,8 +2,8 @@
 const nameOf = (resource) => typeof resource === "string" ? resource : resource.toModel().name;
 /**
 * One client over the app's own API and the sources it draws resources from: a call about a resource goes to the API
-* that serves it (`sourceOf` gives a source's client, or `undefined` for the app's own), and `meta` and `invoke` go to
-* the app's own. A batch goes to the one API all its writes are for; one that writes to two cannot be atomic, so it is
+* that serves it (`sourceOf` gives a source's client, or `undefined` for the app's own), and `meta`, `invoke` and the
+* public forms go to the app's own. A batch goes to the one API all its writes are for; one that writes to two cannot be atomic, so it is
 * refused before anything is sent.
 */
 const routedClient = (own, sourceOf) => {
@@ -16,8 +16,12 @@ const routedClient = (own, sourceOf) => {
 		update: (resource, key, patch, etag) => to(resource).update(resource, key, patch, etag),
 		remove: (resource, key, options) => to(resource).remove(resource, key, options),
 		undelete: (resource, key) => to(resource).undelete(resource, key),
+		generate: (resource, key, action) => to(resource).generate(resource, key, action),
 		reveal: (resource, key, field) => to(resource).reveal(resource, key, field),
 		history: (resource, key, options) => to(resource).history(resource, key, options),
+		comments: (resource, key, options) => to(resource).comments(resource, key, options),
+		comment: (resource, key, input) => to(resource).comment(resource, key, input),
+		mentionable: (resource, key, query) => to(resource).mentionable(resource, key, query),
 		batchWrite: (ops) => {
 			const apis = [...new Set(ops.map((op) => to(op.resource)))];
 			if (apis.length > 1) return Promise.reject(/* @__PURE__ */ new Error(`A batch writes to one API, but these writes are for ${[...new Set(ops.map((op) => nameOf(op.resource)))].join(", ")}, which different APIs serve`));
@@ -31,7 +35,10 @@ const routedClient = (own, sourceOf) => {
 		seek: (resource, params) => to(resource).seek(resource, params),
 		meta: (etag, options) => own.meta(etag, options),
 		invoke: (name, options) => own.invoke(name, options),
-		upload: (resource, field, file, options) => to(resource).upload(resource, field, file, options)
+		upload: (resource, field, file, options) => to(resource).upload(resource, field, file, options),
+		form: (name) => own.form(name),
+		formChallenge: (name) => own.formChallenge(name),
+		submitForm: (name, values, proof) => own.submitForm(name, values, proof)
 	};
 };
 //#endregion

package/dist/types.d.ts

@@ -34,6 +34,70 @@ export type HistoryChange = {
   /** The database role that wrote; `null` when unknown. */
   databaseRole: string | null;
 };
+/** A public form as `/-/forms/<name>` draws it: its fields as `/meta` would give them, with their hints, and no more. */
+export type PublicForm = {
+  name: string;
+  /** The page's heading, when the form gives one; else the view's singular name. */
+  title?: string;
+  /** The fields a visitor fills in, in order. */
+  fields: string[];
+  /** What the page shows once the form is sent. */
+  thanks: string;
+  /** The resource restricted to the form's fields (and its key). */
+  resource: ResourceModel;
+  /** The view's names and the form fields' hints. */
+  view: ViewModel;
+};
+/** A public form's bot check as the server hands it out: an ALTCHA proof-of-work challenge, solved with `altcha-lib`. */
+export type FormChallenge = {
+  parameters: {
+    algorithm: string;
+    nonce: string;
+    salt: string;
+    cost: number;
+    keyLength: number;
+    keyPrefix: string;
+    keySignature?: string;
+    expiresAt?: number;
+    data?: Record<string, string | number | boolean | null>;
+  };
+  signature?: string;
+};
+/** A solved bot check, sent with the form: the challenge as it came, and the solver's answer. */
+export type FormProof = {
+  challenge: FormChallenge;
+  solution: {
+    counter: number;
+    derivedKey: string;
+  };
+};
+/** Someone a comment names: its author or a person it mentions, with their name when the server knows it. */
+export type CommentPerson = {
+  id: string;
+  name?: string;
+};
+/** One comment on a record, as `comments` reads it. */
+export type RecordComment = {
+  id: string;
+  /** When it was written, ISO 8601. */
+  createdAt: string;
+  /** Plain text, as written. */
+  body: string;
+  author: CommentPerson;
+  /** The users it mentions, each once. */
+  mentions: CommentPerson[];
+};
+/** A page of a record's comments, newest first. */
+export type CommentPage = {
+  items: RecordComment[];
+  /** `""` on the last page. */
+  nextPageToken: string;
+};
+/** Someone a comment on a record may mention: a user who may read the record. */
+export type MentionableUser = {
+  id: string;
+  name: string;
+};
 /** A page of a record's history, newest first. */
 export type HistoryPage = {
   items: HistoryChange[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/client",
-  "version": "0.21.6",
+  "version": "0.21.8",
   "description": "Typed fetch client for the Protobase REST API.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,8 +30,8 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
-    "@protobase/layout": "0.21.6",
-    "@protobase/schema": "0.21.6",
+    "@protobase/layout": "0.21.8",
+    "@protobase/schema": "0.21.8",
     "@simplewebauthn/browser": "^13.3.0",
     "better-auth": "^1.7.7"
   }