@protobase/client 0.12.22 → 0.13.3

package/dist/client.d.ts

@@ -1,7 +1,7 @@
-import { FilterInput, ListParams } from "./query-string.js";
+import { FilterInput, ListParams, MapParams } from "./query-string.js";
 import { ClientOptions } from "./transport.js";
 import { UploadProgress } from "./upload-request.js";
-import { BatchOp, BatchResult, Facet, Histogram, ListPage, MetaResult, RecordOf, ResourceRef, Series, SeriesParams, Stored } from "./types.js";
+import { BatchOp, BatchResult, Facet, Histogram, ListPage, MapResult, MetaResult, 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. */
@@ -65,6 +65,7 @@ export declare const createClient: (options?: ClientOptions) => {
     filter?: FilterInput;
     buckets?: number;
   }) => Promise<Histogram>;
+  map: <R extends ResourceRef>(resource: R, params: MapParams) => Promise<MapResult<RecordOf<R>>>;
   seek: <R extends ResourceRef>(resource: R, params: ListParams & {
     position: number;
   }) => Promise<ListPage<RecordOf<R>>>;

package/dist/client.js

@@ -179,6 +179,29 @@ const createClient = (options = {}) => {
 			})
 		})).json();
 	};
+	/**
+	* The records in a map's view, its bounding box being part of `filter`: the records themselves when few match or the
+	* map is close, else buckets of them on a grid sized for `zoom`.
+	*/
+	const map = async (resource, params) => {
+		const body = await (await send({
+			method: "GET",
+			path: `/${nameOf(resource)}:map`,
+			query: queryString({
+				latitude: params.latitude,
+				longitude: params.longitude,
+				zoom: params.zoom,
+				filter: filterText(params.filter) || void 0,
+				order_by: params.orderBy,
+				fields: params.fields?.join(",")
+			})
+		})).json();
+		return {
+			items: body.items.map((item) => withFileOrigin(item, origin)),
+			buckets: body.buckets,
+			totalSize: body.total_size
+		};
+	};
 	/** The page that starts at row `position` of a sort (scrollbar jumps), with the tokens of its own neighbours. Past the end it is empty. */
 	const seek = async (resource, params) => {
 		const response = await send({
@@ -259,6 +282,7 @@ const createClient = (options = {}) => {
 		facets,
 		series,
 		histogram,
+		map,
 		seek,
 		meta,
 		invoke,

package/dist/file-urls.d.ts

@@ -0,0 +1,8 @@
+import { StoredFile } from "./types.js";
+//#region src/file-urls.d.ts
+/**
+ * The link of a stored file, or of its variant by that name when it has one (`fileUrl(listing.photo, 'card')`); the
+ * file's own link otherwise, and `undefined` for a missing file or one without a link.
+ */
+export declare const fileUrl: (file: StoredFile, variant?: string) => string | undefined;
+//#endregion

package/dist/file-urls.js

@@ -1,21 +1,36 @@
 //#region src/file-urls.ts
+const isPath = (url) => url.startsWith("/") && !url.startsWith("//");
 const isFileAtPath = (value) => {
 	if (typeof value !== "object" || value === null) return false;
 	const { uri, url } = value;
-	return typeof uri === "string" && typeof url === "string" && url.startsWith("/") && !url.startsWith("//");
+	return typeof uri === "string" && typeof url === "string" && isPath(url);
 };
 /** The origin of an absolute `baseUrl`; `undefined` for a path on the page's own origin. */
 const originOf = (baseUrl) => baseUrl !== void 0 && URL.canParse(baseUrl) ? new URL(baseUrl).origin : void 0;
+const fromOrigin = (file, origin) => ({
+	...file,
+	url: `${origin}${file.url}`,
+	...file.variants && { variants: Object.fromEntries(Object.entries(file.variants).map(([name, variant]) => [name, isPath(variant.url) ? {
+		...variant,
+		url: `${origin}${variant.url}`
+	} : variant])) }
+});
 /**
-* Makes each file of a record download from `origin`: the API answers a file's URL as a path on its own origin, which a
-* page on another origin, or code outside a page, cannot follow. Without an origin the record is returned as it is.
+* Makes each file of a record download from `origin`, its variants too: the API answers a file's URL as a path on its
+* own origin, which a page on another origin, or code outside a page, cannot follow. Without an origin the record is
+* returned as it is.
 */
 const withFileOrigin = (record, origin) => {
 	if (origin === void 0 || typeof record !== "object" || record === null) return record;
-	return Object.fromEntries(Object.entries(record).map(([name, value]) => [name, isFileAtPath(value) ? {
-		...value,
-		url: `${origin}${value.url}`
-	} : value]));
+	return Object.fromEntries(Object.entries(record).map(([name, value]) => [name, isFileAtPath(value) ? fromOrigin(value, origin) : value]));
+};
+/**
+* The link of a stored file, or of its variant by that name when it has one (`fileUrl(listing.photo, 'card')`); the
+* file's own link otherwise, and `undefined` for a missing file or one without a link.
+*/
+const fileUrl = (file, variant) => {
+	if ("missing" in file) return void 0;
+	return (variant === void 0 ? void 0 : file.variants?.[variant]?.url) ?? file.url;
 };
 //#endregion
-export { originOf, withFileOrigin };
+export { fileUrl, originOf, withFileOrigin };

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-import { FilterInput, ListParams, filterText, listWire } from "./query-string.js";
+import { FilterInput, ListParams, MapParams, filterText, listWire } from "./query-string.js";
 import { ClientOptions } from "./transport.js";
 import { UploadProgress } from "./upload-request.js";
-import { BatchOp, BatchRef, BatchResult, Facet, Histogram, HistogramBucket, ListPage, Meta, MetaResult, PluginRef, RecordOf, RecordPermissions, ResourcePermissions, ResourceRef, Series, SeriesParams, SeriesPoint, SourceRef, Stored, StoredFile } from "./types.js";
+import { BatchOp, BatchRef, BatchResult, Facet, Histogram, HistogramBucket, ListPage, MapBounds, MapBucket, MapResult, Meta, MetaResult, PluginRef, RecordOf, RecordPermissions, 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";
 import { routedClient } from "./routed-client.js";
 import { SourceMeta, sourceMeta } from "./source-meta.js";
 import { SignInPolicy, SignInPolicyClient, SignInPolicyState, SignInRule, StaffAccessRule } from "./sign-in-policy.js";
@@ -17,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, RuntimePolicy, RuntimeStatus, createRuntimeClient } from "./runtime.js";
-export { type AccountSecurity, type AccountSignIn, type ActiveRole, 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 InvitationPreview, type InvitationSent, type InvokeOptions, type ListPage, type ListParams, 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 RequiredSetup, type ResourcePermissions, type ResourceRef, type RoleLabel, type RoleOption, type RolesClient, type RuntimeClient, type RuntimeClientOptions, type RuntimePolicy, type RuntimeStatus, 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 TwoFactorMethod, type UploadOptions, type UploadProgress, type UploadResult, createAssistantClient, createAuthSession, createClient, createRuntimeClient, createStaticSession, filterText, isApiError, listWire, routedClient, sourceMeta, tokenExpiry };
+export { type AccountSecurity, type AccountSignIn, type ActiveRole, 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 InvitationPreview, type InvitationSent, type InvokeOptions, type ListPage, type ListParams, type MapBounds, type MapBucket, 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 RequiredSetup, type ResourcePermissions, type ResourceRef, type RoleLabel, type RoleOption, type RolesClient, type RuntimeClient, type RuntimeClientOptions, type RuntimePolicy, type RuntimeStatus, 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/index.js

@@ -1,4 +1,5 @@
 import { filterText, listWire } from "./query-string.js";
+import { fileUrl } from "./file-urls.js";
 import { ApiError, PreconditionFailedError, isApiError } from "./problem.js";
 import { createClient } from "./client.js";
 import { routedClient } from "./routed-client.js";
@@ -8,4 +9,4 @@ import { createAuthSession, tokenExpiry } from "./auth.js";
 import { createStaticSession } from "./static-session.js";
 import { createAssistantClient } from "./assistant.js";
 import { createRuntimeClient } from "./runtime.js";
-export { ApiError, AuthError, PreconditionFailedError, createAssistantClient, createAuthSession, createClient, createRuntimeClient, createStaticSession, filterText, isApiError, listWire, routedClient, sourceMeta, tokenExpiry };
+export { ApiError, AuthError, PreconditionFailedError, createAssistantClient, createAuthSession, createClient, createRuntimeClient, createStaticSession, fileUrl, filterText, isApiError, listWire, routedClient, sourceMeta, tokenExpiry };

package/dist/query-string.d.ts

@@ -10,6 +10,15 @@ export type ListParams = {
   fields?: string[];
   count?: 'exact';
 };
+/** What `map` asks for: the fields of the position, the map's zoom, and the bounding box in `filter`. */
+export type MapParams = {
+  latitude: string;
+  longitude: string;
+  zoom: number;
+  filter?: FilterInput;
+  orderBy?: string;
+  fields?: string[];
+};
 export declare const filterText: (filter: FilterInput | undefined) => string | undefined;
 /** The snake_case parameters of `GET /{resource}` and the body of `POST /{resource}:search`. */
 export declare const listWire: (params?: ListParams) => {

package/dist/routed-client.js

@@ -25,6 +25,7 @@ const routedClient = (own, sourceOf) => {
 		facets: (resource, field, options) => to(resource).facets(resource, field, options),
 		series: (resource, params) => to(resource).series(resource, params),
 		histogram: (resource, field, options) => to(resource).histogram(resource, field, options),
+		map: (resource, params) => to(resource).map(resource, params),
 		seek: (resource, params) => to(resource).seek(resource, params),
 		meta: (etag, options) => own.meta(etag, options),
 		invoke: (name, options) => own.invoke(name, options),

package/dist/types.d.ts

@@ -54,6 +54,26 @@ export type Histogram = {
   max: number | null;
   buckets: HistogramBucket[];
 };
+/** The corners around some records, in decimal degrees. */
+export type MapBounds = {
+  south: number;
+  west: number;
+  north: number;
+  east: number;
+};
+/** The records in one cell of a map's grid: how many, their mean position, and the bounds around them. */
+export type MapBucket = {
+  count: number;
+  latitude: number;
+  longitude: number;
+  bounds: MapBounds;
+};
+/** The records `map` answers, or buckets of them when many match, never both; `totalSize` counts the matches. */
+export type MapResult<T> = {
+  items: T[];
+  buckets: MapBucket[];
+  totalSize: number;
+};
 /** What the signed-in user may do with a resource; `conditional` operations are decided per record by the server. */
 export type ResourcePermissions = {
   read?: boolean;
@@ -124,9 +144,17 @@ export type Stored<T> = {
   etag: string;
   permissions?: RecordPermissions;
 };
+/** A resized copy of an image, by the field's `.variants()`: its link and type, and the box it is resized into. */
+export type StoredFileVariant = {
+  url: string;
+  type: string;
+  width?: number;
+  height?: number;
+};
 /**
  * A file field as records carry it. `url` downloads it: signed and valid one to two hours for a private file, permanent
- * for a public one. Send `uri` back unchanged to keep the file, or `null` to clear it.
+ * for a public one. An image may have `variants` by name and a `placeholder`, its ThumbHash in base64. Send `uri` back
+ * unchanged to keep the file, or `null` to clear it.
  */
 export type StoredFile = {
   uri: string;
@@ -134,6 +162,8 @@ export type StoredFile = {
   type: string;
   size?: number;
   url?: string;
+  placeholder?: string;
+  variants?: Record<string, StoredFileVariant>;
 } | {
   uri: string;
   missing: true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/client",
-  "version": "0.12.22",
+  "version": "0.13.3",
   "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.12.22",
-    "@protobase/schema": "0.12.22",
+    "@protobase/layout": "0.13.3",
+    "@protobase/schema": "0.13.3",
     "@simplewebauthn/browser": "^13.3.0",
     "better-auth": "^1.7.7"
   }