@standards/client 0.0.0-stage → 1.0.0-alpha.382

package/dist/create-standards-3ODOXxRV.d.ts

@@ -0,0 +1,439 @@
+
+import { r as MultipartRequestOptions, s as TransportConfig, t as HttpTransport } from "./http-transport-DBgedLFQ.js";
+import { AggregateRecordsOptions, ContentViewDefinition, DocumentFile, ExtractRecord, ExtractRecordInputStrict, ExtractRecordUpdateStrict, FilterRule, ObjectBuilderLike, ObjectBuilderLike as ObjectBuilderLike$1, ObjectDefinition, RecordAccessRole, RecordAggregates, RecordAudience, RuleValue, SchemaGroupPresentation, SchemaSourceResolution, ViewDeclaration } from "@standards/schema";
+//#region src/define-schema-source.d.ts
+/**
+ * `@standards/constants` (the home of `IconName`) is not a dependency of this
+ * package; deriving the type from `SchemaGroupPresentation` avoids adding one
+ * just for a type alias.
+ */
+type IconName = NonNullable<SchemaGroupPresentation["icon"]>;
+type ViewInput = ContentViewDefinition | ViewDeclaration | {
+  build(): ContentViewDefinition | ViewDeclaration;
+};
+interface SchemaSourceConfig<TObjects extends readonly ObjectBuilderLike[]> {
+  /**
+   * Slug identity of the source, required to sync. Write it by hand, or derive
+   * it with `sourceIdFromPackageName(packageJson.name)`.
+   */
+  id?: string;
+  objects: TObjects;
+  views?: ViewInput[];
+  label?: string;
+  icon?: IconName;
+}
+/** What `defineSchemaSource` returns: the declaration only — nothing is built until it is resolved. */
+interface SchemaSource<TObjects extends readonly ObjectBuilderLike[] = readonly ObjectBuilderLike[]> {
+  readonly id: string | null;
+  /** The builders, kept for type inference of the typed client (`db.<camelCaseName>`). */
+  readonly builders: TObjects;
+  readonly views: readonly ViewInput[];
+  readonly label: string | null;
+  readonly icon: IconName | null;
+}
+/** A source built, validated and hashed — what a sync sends. */
+interface ResolvedSchemaSource {
+  id: string | null;
+  /** sha256 hex of `canonicalStringify({ objects, views })` — the same digest the server recomputes. */
+  hash: string;
+  objects: ObjectDefinition[];
+  views: ContentViewDefinition[];
+  label: string | null;
+  icon: IconName | null;
+}
+/** sha256 hex over the canonical JSON, with Web Crypto (Node >= 20, Edge, browsers). */
+declare function hashSchemaSource(payload: {
+  objects: ObjectDefinition[];
+  views: ContentViewDefinition[];
+}): Promise<string>;
+/** Declares the schema an external codebase owns. Does no work: see `resolveSchemaSource`. */
+declare function defineSchemaSource<const TObjects extends readonly ObjectBuilderLike[]>(config: SchemaSourceConfig<TObjects>): SchemaSource<TObjects>;
+/** Builds, validates and hashes a source once; later calls share the same promise. */
+declare function resolveSchemaSource(source: SchemaSource): Promise<ResolvedSchemaSource>;
+/** `@acme/crm` -> `acme-crm`; refuses a name the server would refuse as a source id. */
+declare function sourceIdFromPackageName(packageName: string): string;
+//#endregion
+//#region src/files/file-input.d.ts
+/**
+ * What the files and documents methods upload: a `File` (or any `Blob` carrying
+ * a `name`) with a non-empty filename and MIME type. The server checks the MIME
+ * type, the extension and the file signature against each other, so all three
+ * travel with the bytes. A `Buffer` or a path is not an input: wrap the bytes in
+ * `new File([bytes], "name.png", { type: "image/png" })`.
+ */
+type FileInput = Blob & {
+  readonly name: string;
+};
+/**
+ * The timeout of one upload's request, in ms (#4741). A large file on a slow
+ * link outlives the client's `timeoutMs` (30 s by default) and surfaces as a
+ * connection failure, possibly after the server stored it — so raise it for
+ * large uploads rather than retrying a timed-out attach.
+ */
+interface UploadTimeoutOption {
+  timeoutMs?: number;
+}
+//#endregion
+//#region src/files/documents-api.d.ts
+interface AttachToRecordInput extends UploadTimeoutOption {
+  objectName: string;
+  recordId: string;
+  /** The record's `document` attribute; the server defaults to `attachments`. */
+  attributeName?: string;
+  /** Append to this existing document's pack instead of creating a document. */
+  documentId?: string;
+  /** The new document's title; the server defaults to the filename without its extension. */
+  title?: string;
+  /**
+   * The bytes to upload, private, in the same request — the input
+   * `files.upload` takes. The attach route takes one file per call: append
+   * more by passing the returned `document.id` as `documentId`. An
+   * already-uploaded file is not an input, so a public upload can never end up
+   * in a document.
+   */
+  file: FileInput;
+}
+interface AttachToRecordResult {
+  document: {
+    id: string;
+    title: string;
+  };
+  file: DocumentFile;
+  /** `created`: a new document on the record; `appended`: added to `documentId`'s pack. */
+  action: "created" | "appended";
+}
+interface DocumentsApi {
+  /**
+   * Upload a file and attach it to a record's document attribute in ONE
+   * multipart `POST /records/:object/:id/documents/attach`. The server
+   * validates the file against the attribute and deletes the upload if the
+   * attach fails, so an error never leaves an orphaned file.
+   */
+  attachToRecord(input: AttachToRecordInput): Promise<AttachToRecordResult>;
+  /** The document's files in pack order (`GET /documents/:id/files`). */
+  listFiles(documentId: string): Promise<DocumentFile[]>;
+}
+/** The two verbs this module needs, typed non-generically so a stub satisfies it. */
+interface DocumentsTransport {
+  get(path: string): Promise<unknown>;
+  postMultipart(path: string, form: FormData, options?: MultipartRequestOptions): Promise<unknown>;
+}
+declare function createDocumentsApi(transport: DocumentsTransport): DocumentsApi;
+//#endregion
+//#region src/files/files-api.d.ts
+interface UploadFileBase extends UploadTimeoutOption {
+  file: FileInput;
+  /** Stored as the file's folder (`folderPath` on `POST /files/upload`). */
+  folderPath?: string;
+}
+/** Anyone holding the returned `publicUrl` can open the file. A public file never joins a document. */
+interface UploadPublicFileInput extends UploadFileBase {
+  public: true;
+}
+/** The default: readable through a signed URL from `getDownloadUrl`. */
+interface UploadPrivateFileInput extends UploadFileBase {
+  public?: false;
+}
+type UploadFileInput = UploadPublicFileInput | UploadPrivateFileInput;
+interface UploadedFileBase {
+  id: string;
+  /** The stored (sanitized) filename. */
+  name: string;
+  mimeType: string;
+  size: number;
+}
+interface PublicUploadedFile extends UploadedFileBase {
+  isPublic: true;
+  /** `{publicFilesUrl}/{id}`: permanent, and never carries a credential. */
+  publicUrl: string;
+}
+interface PrivateUploadedFile extends UploadedFileBase {
+  isPublic: false;
+  publicUrl?: never;
+}
+/** Discriminated on `isPublic`: only the public branch has a `publicUrl`. */
+type UploadedFile = PublicUploadedFile | PrivateUploadedFile;
+interface FilesApi {
+  /** One multipart `POST /files/upload`. */
+  upload(input: UploadPublicFileInput): Promise<PublicUploadedFile>;
+  upload(input: UploadPrivateFileInput): Promise<PrivateUploadedFile>;
+  upload(input: UploadFileInput): Promise<UploadedFile>;
+  /** A fresh signed read URL (`GET /files/:id/url`); it expires, so ask again each time. */
+  getDownloadUrl(fileId: string): Promise<string>;
+}
+/** The one verb this module needs: the `files` operations. */
+type FilesTransport = Pick<HttpTransport, "call">;
+declare function createFilesApi(transport: FilesTransport): FilesApi;
+//#endregion
+//#region src/object-keys.d.ts
+/** `daily-stats` → `dailyStats`. Object names are kebab-case (enforced by the builder). */
+type CamelCase<S extends string> = S extends `${infer Head}-${infer Tail}` ? `${Head}${Capitalize<CamelCase<Tail>>}` : S;
+//#endregion
+//#region src/records/query.d.ts
+type Attr<TBuilder> = keyof ExtractRecord<TBuilder> & string;
+/**
+ * The builder's own attributes keep their exact types (a `select` refuses an
+ * option it does not declare); runtime-added custom attributes stay writable
+ * through the open index. `ExtractRecordInput`'s own index is typed
+ * `CustomAttributeValue`, which has no `Date` member and would reject the very
+ * date values the REST API accepts — hence the strict variant plus this index.
+ */
+type RecordInput<TBuilder> = ExtractRecordInputStrict<TBuilder> & {
+  [key: string]: unknown;
+};
+type RecordUpdate<TBuilder> = ExtractRecordUpdateStrict<TBuilder> & {
+  [key: string]: unknown;
+};
+/** What `export()` takes beside its columns. */
+interface RecordsExportOptions {
+  /** Export only these records (at most `EXPORT_MAX_IDS`, 20 000). */
+  ids?: string[];
+  /** BCP 47 locale numbers, dates and headers are written in. Default: the request's. */
+  locale?: string;
+  /** IANA zone dates are read in. Default: the caller's (`Intl`). */
+  timezone?: string;
+  /** The tab name the downloaded file is named after (`{object}-{tab}-{date}.csv`). */
+  filename?: string;
+}
+/** What `aggregate()` takes: the aggregate contract minus the query, which is this one. */
+type RecordsAggregateOptions = Omit<AggregateRecordsOptions, "query">;
+interface FetchResult<TBuilder> {
+  records: ExtractRecord<TBuilder>[];
+  total: number | null;
+}
+/** One input `createMany` did not create; `index` is its position in the caller's array. */
+interface CreateManyError {
+  index: number;
+  error: string;
+}
+interface CreateManyResult<TBuilder> {
+  created: ExtractRecord<TBuilder>[];
+  errors: CreateManyError[];
+}
+/** One `{ id, data }` pair of `updateMany`; `data` is typed like `update`'s patch. */
+interface UpdateManyEntry<TBuilder> {
+  id: string;
+  data: RecordUpdate<TBuilder>;
+}
+/** One entry `updateMany` did not update. */
+/**
+ * One id `updateMany` did not update. `code` is the server's `SchemaErrorCode`
+ * when the runtime raised the refusal (`SCHEMA_FORBIDDEN`,
+ * `SCHEMA_SYSTEM_ENTITY_IMMUTABLE`, …); a database-side rejection carries its message only.
+ */
+interface UpdateManyError {
+  id: string;
+  error: string;
+  code?: string;
+}
+interface UpdateManyResult<TBuilder> {
+  updated: ExtractRecord<TBuilder>[];
+  errors: UpdateManyError[];
+}
+/**
+ * One id `deleteMany` did not delete. `code` is the server's `SchemaErrorCode`
+ * when the runtime raised the refusal (`SCHEMA_FORBIDDEN`,
+ * `SCHEMA_RECORD_NOT_FOUND`, …); a database-side rejection carries its message only.
+ */
+interface DeleteManyError {
+  id: string;
+  error: string;
+  code?: string;
+}
+interface DeleteManyResult {
+  deleted: string[];
+  errors: DeleteManyError[];
+}
+interface RecordsQuery<TBuilder> {
+  eq(attribute: Attr<TBuilder>, value: RuleValue): RecordsQuery<TBuilder>;
+  neq(attribute: Attr<TBuilder>, value: RuleValue): RecordsQuery<TBuilder>;
+  /** Appends rules as they are: any operator, a qualified `property`, `exists`, dynamic values. */
+  where(...rules: (Omit<FilterRule, "attribute"> & {
+    attribute: Attr<TBuilder>;
+  })[]): RecordsQuery<TBuilder>;
+  gt(attribute: Attr<TBuilder>, value: RuleValue): RecordsQuery<TBuilder>;
+  gte(attribute: Attr<TBuilder>, value: RuleValue): RecordsQuery<TBuilder>;
+  lt(attribute: Attr<TBuilder>, value: RuleValue): RecordsQuery<TBuilder>;
+  lte(attribute: Attr<TBuilder>, value: RuleValue): RecordsQuery<TBuilder>;
+  contains(attribute: Attr<TBuilder>, value: RuleValue): RecordsQuery<TBuilder>;
+  notContains(attribute: Attr<TBuilder>, value: RuleValue): RecordsQuery<TBuilder>;
+  startsWith(attribute: Attr<TBuilder>, value: string): RecordsQuery<TBuilder>;
+  endsWith(attribute: Attr<TBuilder>, value: string): RecordsQuery<TBuilder>;
+  in(attribute: Attr<TBuilder>, values: string[]): RecordsQuery<TBuilder>;
+  notIn(attribute: Attr<TBuilder>, values: string[]): RecordsQuery<TBuilder>;
+  isEmpty(attribute: Attr<TBuilder>): RecordsQuery<TBuilder>;
+  isNotEmpty(attribute: Attr<TBuilder>): RecordsQuery<TBuilder>;
+  or(): RecordsQuery<TBuilder>;
+  orderBy(attribute: Attr<TBuilder>, direction?: "asc" | "desc"): RecordsQuery<TBuilder>;
+  limit(count: number): RecordsQuery<TBuilder>;
+  offset(count: number): RecordsQuery<TBuilder>;
+  search(query: string): RecordsQuery<TBuilder>;
+  /**
+   * `POST /records/<object>/export`: this query's search, filters and sorts as
+   * a CSV with the given attributes as columns, in order. Resolves to the
+   * unread `Response` (`text/csv`, UTF-8 BOM, CRLF) so a large export can be
+   * streamed; a refusal (`EXPORT_TOO_LARGE`, validation) rejects before any byte.
+   * `ids` restricts it to those records; `timezone` (default: the caller's) is
+   * the zone dates are read in; `filename` is the tab name the file is named after.
+   */
+  export(columns: string[], options?: RecordsExportOptions): Promise<Response>;
+  /**
+   * `POST /records/<object>/aggregate`: one measure over this query's records,
+   * optionally grouped and compared with the previous period. The query's
+   * filters and relation scope are measured; its sorts and limit are ignored,
+   * and a search is refused (`AGGREGATE_SEARCH_UNSUPPORTED`). `timezone`
+   * defaults to the caller's.
+   */
+  aggregate(options: RecordsAggregateOptions): Promise<RecordAggregates>;
+  fetch(): Promise<FetchResult<TBuilder>>;
+  /**
+   * Every matching record, walked in pages of {@link RECORDS_PAGE_SIZE} with
+   * this query's filters, sorts and search while the response says
+   * `page.hasMore`, resuming at its `nextOffset`. An
+   * explicit `limit(n)` caps the total, an explicit `offset(k)` is where the
+   * walk starts. A page that fails rejects the whole call.
+   */
+  all(): Promise<ExtractRecord<TBuilder>[]>;
+  single(): Promise<ExtractRecord<TBuilder> | null>;
+  get(id: string): Promise<ExtractRecord<TBuilder>>;
+  create(input: RecordInput<TBuilder>): Promise<ExtractRecord<TBuilder>>;
+  update(id: string, patch: RecordUpdate<TBuilder>): Promise<ExtractRecord<TBuilder>>;
+  delete(id: string): Promise<void>;
+  /**
+   * `POST /records/<object>/bulk-create`, 100 inputs per request, sent one after
+   * another. A refused input is reported in `errors` (never thrown); a failed
+   * request rejects, and the chunks before it stay created. Every record is
+   * workspace-visible: the route takes no visibility.
+   */
+  createMany(inputs: readonly RecordInput<TBuilder>[]): Promise<CreateManyResult<TBuilder>>;
+  /** `POST /records/<object>/bulk-update`, chunked and reported like `createMany`. */
+  updateMany(entries: readonly UpdateManyEntry<TBuilder>[]): Promise<UpdateManyResult<TBuilder>>;
+  /** `POST /records/<object>/bulk-delete`, chunked and reported like `createMany`. */
+  deleteMany(ids: readonly string[]): Promise<DeleteManyResult>;
+  /** Who can reach this private record beyond its owner: `GET /records/<object>/<id>/access`. */
+  listAccess(id: string): Promise<RecordAudience>;
+  /** Share a private record you own or edit: `PUT /records/<object>/<id>/access/<actorId>`. */
+  grantAccess(id: string, actorId: string, role: RecordAccessRole): Promise<RecordAudience>;
+  /** Remove your manual share: `DELETE /records/<object>/<id>/access/<actorId>`. */
+  revokeAccess(id: string, actorId: string): Promise<RecordAudience>;
+  /** Make a shared record private again — every manual share at once: `DELETE /records/<object>/<id>/access`. */
+  clearAccess(id: string): Promise<RecordAudience>;
+}
+/**
+ * The builder shape `from(objectName: string)` stands in for: no declared
+ * attributes, so `ExtractRecord` resolves to an open record and `records` is a
+ * usable `Record<string, unknown> & RecordMetadata` array instead of `never[]`.
+ * `build()` returns `never` because there is no definition to build — the
+ * string overload never calls it.
+ */
+interface UntypedBuilder {
+  readonly _types: {
+    name: string;
+    record: Record<string, unknown>;
+    input: Record<string, unknown>;
+    update: Record<string, unknown>;
+  };
+  build(): never;
+}
+/** What `standards.from("object-name")` hands back. */
+type UntypedRecordsQuery = RecordsQuery<UntypedBuilder>;
+/**
+ * The verbs this module needs, typed non-generically: the real `Transport`
+ * satisfies it, and so does a hand-rolled stub, which a `Pick` of the generic
+ * signatures would reject. `postRaw` only serves `export()`, which refuses
+ * when a stub leaves it out. Each path is its contract operation's
+ * (`buildOperationPath`, every parameter one encoded segment); the verbs stay
+ * the transport's.
+ */
+interface RecordsTransport {
+  get(path: string): Promise<unknown>;
+  post(path: string, body?: unknown): Promise<unknown>;
+  postRaw?(path: string, body: unknown): Promise<Response>;
+  put(path: string, body?: unknown): Promise<unknown>;
+  delete(path: string): Promise<unknown>;
+}
+/** A builder gives typed records; a bare object name is the untyped escape hatch. */
+declare function createRecordsQuery<TBuilder extends ObjectBuilderLike$1>(transport: RecordsTransport, target: TBuilder): RecordsQuery<TBuilder>;
+declare function createRecordsQuery(transport: RecordsTransport, target: string): UntypedRecordsQuery;
+//#endregion
+//#region src/schema-sync.d.ts
+interface SchemaSourceSummary {
+  sourceId: string;
+  hash: string;
+  appliedAt: string;
+  objectNames: string[];
+  /** Absent on an older server that predates presentation; treated as "no presentation". */
+  label?: string | null;
+  icon?: string | null;
+}
+interface SyncResult {
+  applied: boolean;
+  hash: string;
+  objects?: {
+    created: number;
+    updated: number;
+    deleted: number;
+  };
+  views?: {
+    created: number;
+    updated: number;
+    adopted: number;
+    released: number;
+  };
+}
+/**
+ * What a sync carries besides the source itself.
+ *
+ * `resolutions` resolve the renames and retypes the server refuses as
+ * ambiguous (`SCHEMA_AMBIGUOUS_CHANGE`), which names the exact entries to
+ * send. They travel outside the hash: a source whose hash is already applied
+ * is not pushed, and the resolutions with it. A server older than
+ * `resolutions` answers 400 `Unknown source payload fields` — upgrade the
+ * client and the server together.
+ */
+interface SyncOptions {
+  resolutions?: SchemaSourceResolution[];
+}
+/**
+ * The two verbs a sync needs, typed non-generically: the real `Transport`
+ * satisfies it, and so does a hand-rolled stub, which a `Pick` of the generic
+ * signatures would reject.
+ */
+interface SyncTransport {
+  get(path: string): Promise<unknown>;
+  put(path: string, body?: unknown): Promise<unknown>;
+}
+/** GET the remote summary; PUT when the hash or the presentation differs, or the source was never pushed. */
+declare function syncSchemaSource(transport: SyncTransport, declared: SchemaSource, options?: SyncOptions): Promise<SyncResult>;
+//#endregion
+//#region src/create-standards.d.ts
+type NameOf<B> = B extends {
+  _types: {
+    name: infer N extends string;
+  };
+} ? N : never;
+/** One typed query per object of a source, keyed by the camelCase of its name. */
+type ObjectsOf<TObjects extends readonly ObjectBuilderLike$1[]> = { readonly [B in TObjects[number] as CamelCase<NameOf<B>>]: RecordsQuery<B>; };
+interface Standards {
+  schema: {
+    sync(source: SchemaSource, options?: SyncOptions): Promise<SyncResult>;
+  };
+  /** Untyped access to an object the code does not declare (created at runtime). */
+  from(objectName: string): UntypedRecordsQuery;
+  /** Upload files (private or public) and read them back through signed URLs. */
+  files: FilesApi;
+  /** Attach uploads to a record's document attribute and list a document's files. */
+  documents: DocumentsApi;
+}
+/**
+ * The options `createStandards` takes. Every field of `TransportConfig` is
+ * optional here: on the server a missing `baseUrl` / `apiKey` is read from
+ * `STANDARDS_API_URL` / `STANDARDS_API_KEY`, and an explicit value always wins.
+ */
+type StandardsConfig = Partial<TransportConfig>;
+declare function createStandards<const TObjects extends readonly ObjectBuilderLike$1[]>(config: StandardsConfig & {
+  schema: SchemaSource<TObjects>;
+}): Standards & ObjectsOf<TObjects>;
+declare function createStandards(config?: StandardsConfig): Standards;
+//#endregion
+export { UploadFileInput as A, FileInput as B, UpdateManyResult as C, FilesTransport as D, FilesApi as E, AttachToRecordInput as F, SchemaSource as G, IconName as H, AttachToRecordResult as I, defineSchemaSource as J, SchemaSourceConfig as K, DocumentsApi as L, UploadPublicFileInput as M, UploadedFile as N, PrivateUploadedFile as O, createFilesApi as P, DocumentsTransport as R, UpdateManyError as S, CamelCase as T, ObjectBuilderLike$1 as U, UploadTimeoutOption as V, ResolvedSchemaSource as W, resolveSchemaSource as X, hashSchemaSource as Y, sourceIdFromPackageName as Z, RecordsExportOptions as _, SchemaSourceSummary as a, UntypedRecordsQuery as b, syncSchemaSource as c, DeleteManyError as d, DeleteManyResult as f, RecordsAggregateOptions as g, RecordUpdate as h, createStandards as i, UploadPrivateFileInput as j, PublicUploadedFile as k, CreateManyError as l, RecordInput as m, Standards as n, SyncOptions as o, FetchResult as p, ViewInput as q, StandardsConfig as r, SyncResult as s, ObjectsOf as t, CreateManyResult as u, RecordsQuery as v, createRecordsQuery as w, UpdateManyEntry as x, UntypedBuilder as y, createDocumentsApi as z };