@standards/client 1.0.0-alpha.419 → 1.0.0-alpha.425

package/dist/{create-standards-BWOo2EZw.d.ts → create-standards-De7-xdtZ.d.ts}

@@ -1,6 +1,7 @@
 
-import { r as MultipartRequestOptions, s as TransportConfig, t as HttpTransport } from "./http-transport-BxJhcXjy.js";
-import { AggregateRecordsOptions, BundleBuilder, DocumentFile, ExtractRecord, ExtractRecordInputStrict, ExtractRecordUpdateStrict, FilterRule, ObjectBuilderLike, RecordAccessRole, RecordAggregates, RecordAudience, RuleValue, SchemaSourceResolution, SyncBundleResult, UsageReport, UsageScope } from "@standards/schema";
+import { C as OperationTransport, T as TransportConfig, r as InProcessTransport, t as AppClient, v as HttpTransport } from "./app-_CiXRLoD.js";
+import { AggregateRecordsOptions, BundleBuilder, ExtractRecord, ExtractRecordInputStrict, ExtractRecordUpdateStrict, FilterRule, ObjectBuilderLike, RecordAccessRole, RecordAggregates, RecordAudience, RuleValue, SchemaSourceResolution, SyncBundleResult } from "@standards/schema";
+import { ActorId } from "@standards/schema/api";
 /**
  * What a sync carries besides the bundle itself.
  *
@@ -12,123 +13,10 @@ import { AggregateRecordsOptions, BundleBuilder, DocumentFile, ExtractRecord, Ex
 interface SyncBundleOptions {
   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>;
-}
+/** Both calls are contract operations, on any transport. */
+type SyncTransport = Pick<HttpTransport, "call">;
 /** GET the installed summary; PUT the built bundle when its hash, label, description or uses differ, or it was never synced. */
 declare function syncBundle(transport: SyncTransport, bundle: BundleBuilder<string, readonly ObjectBuilderLike[]>, options?: SyncBundleOptions): Promise<SyncBundleResult>;
-/**
- * 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;
-}
-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;
-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;
 /** `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;
 type Attr<TBuilder> = keyof ExtractRecord<TBuilder> & string;
@@ -145,6 +33,33 @@ type RecordInput<TBuilder> = ExtractRecordInputStrict<TBuilder> & {
 type RecordUpdate<TBuilder> = ExtractRecordUpdateStrict<TBuilder> & {
   [key: string]: unknown;
 };
+/** What `create()` takes beside the values. */
+interface RecordCreateOptions {
+  /**
+   * Create the record even when required attributes are missing. The values
+   * given are still validated.
+   * @default false
+   */
+  allowDraft?: boolean;
+  /**
+   * The record's `metadata`: application state kept beside its values, never
+   * shown as an attribute. System keys are dropped.
+   */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * What `update()` takes beside the patch. No `allowDraft`: the server already
+ * validates every update as a draft, so a required attribute the patch leaves
+ * out is never refused.
+ */
+interface RecordUpdateOptions {
+  /**
+   * Keys shallow-merged into the record's `metadata`: each one replaced whole,
+   * `null` removes it, the keys not named stay. Written with the patch in one
+   * transaction.
+   */
+  metadata?: Record<string, unknown>;
+}
 /** What `export()` takes beside its columns. */
 interface RecordsExportOptions {
   /** Export only these records (at most `EXPORT_MAX_IDS`, 20 000). */
@@ -257,8 +172,27 @@ interface RecordsQuery<TBuilder> {
   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>>;
+  /**
+   * `POST /records/<object>`. `allowDraft` creates the record with required
+   * attributes missing (so its input types every attribute as optional);
+   * `metadata` is the record's application state.
+   */
+  create(input: RecordInput<TBuilder>, options?: RecordCreateOptions): Promise<ExtractRecord<TBuilder>>;
+  create(input: RecordUpdate<TBuilder>, options: RecordCreateOptions & {
+    allowDraft: true;
+  }): Promise<ExtractRecord<TBuilder>>;
+  /**
+   * `PUT /records/<object>/<id>`: merges the patch into the record. The server
+   * validates every update as a draft, so there is no `allowDraft`.
+   *
+   * With `metadata`, the patch and the metadata are written together by one
+   * `record.set` step of `POST /operations`, in one transaction; the record is
+   * read first (`GET /records/<object>/<id>`) for the object id the step
+   * names. A refused step rejects with the `StandardsRequestError` its code
+   * maps to (`StandardsAuthError` for a 403), with that code and status but
+   * no field `details`, which the same refusal on `PUT` carries.
+   */
+  update(id: string, patch: RecordUpdate<TBuilder>, options?: RecordUpdateOptions): Promise<ExtractRecord<TBuilder>>;
   delete(id: string): Promise<void>;
   /**
    * `POST /records/<object>/bulk-create`, 100 inputs per request, sent one after
@@ -299,38 +233,16 @@ interface UntypedBuilder {
 /** 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.
+ * Every records call is a contract operation (`call`), on any transport, the
+ * in-process one included. `export()` alone reads the CSV as it streams, so it
+ * needs an HTTP transport's `postRaw`.
  */
-interface RecordsTransport {
-  get(path: string): Promise<unknown>;
-  post(path: string, body?: unknown): Promise<unknown>;
+type RecordsTransport = Pick<HttpTransport, "call"> & {
   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>(transport: RecordsTransport, target: TBuilder): RecordsQuery<TBuilder>;
 declare function createRecordsQuery(transport: RecordsTransport, target: string): UntypedRecordsQuery;
-interface UsageReportInput {
-  /** First day of the window, `YYYY-MM-DD` (UTC, inclusive). */
-  from: string;
-  /** Last day of the window, `YYYY-MM-DD` (UTC, inclusive); at most 366 days after `from`. */
-  to: string;
-  /** `me` (the default): the caller's own usage. `workspace`: every member's, gated on `billing:read`. */
-  scope?: UsageScope;
-}
-interface UsageApi {
-  /** AI usage and cost over an inclusive UTC day window (`GET /ai/usage`). */
-  report(input: UsageReportInput): Promise<UsageReport>;
-}
-/** The one verb this module needs: the `ai.usage` operation. */
-type UsageTransport = Pick<HttpTransport, "call">;
-declare function createUsageApi(transport: UsageTransport): UsageApi;
 type NameOf<B> = B extends {
   _types: {
     name: infer N extends string;
@@ -342,28 +254,82 @@ type ObjectsOf<TObjects extends readonly ObjectBuilderLike[]> = { readonly [B in
 type AnyBundle = BundleBuilder<string, readonly ObjectBuilderLike[]>;
 /** The object builders of every bundle in a tuple: what the typed client infers from. */
 type ObjectsOfBundles<TBundles extends readonly AnyBundle[]> = TBundles[number]["objectBuilders"];
-interface Standards {
-  bundles: {
-    /** Sync a bundle to the workspace; a no-op (`applied: false`) when it already holds this version. */
-    sync(bundle: AnyBundle, options?: SyncBundleOptions): Promise<SyncBundleResult>;
+type ContractSync = AppClient["bundles"]["sync"];
+/** `bundles.sync`, either way: from your bundle's builder, or the contract's call. */
+interface BundlesSync {
+  /**
+   * Build `bundle`, compare it with the version the workspace holds, and put
+   * it only when it changed: `{ applied: false }` when it already holds it.
+   */
+  (bundle: AnyBundle, options?: SyncBundleOptions): Promise<SyncBundleResult>;
+  /** The contract's call, with an artifact you built yourself. */
+  (...args: Parameters<ContractSync>): ReturnType<ContractSync>;
+}
+/**
+ * The client: every operation of the contract at the root, by group and
+ * verb (`decisions.list`, `users.get`, `files.upload`…), with your bundles'
+ * objects beside them as typed queries (see {@link StandardsOf}).
+ */
+type Standards = Omit<AppClient, "bundles"> & {
+  readonly bundles: Omit<AppClient["bundles"], "sync"> & {
+    readonly sync: BundlesSync;
   };
   /** 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;
-  /** AI usage and cost of the caller or the whole workspace. */
-  usage: UsageApi;
-}
+  /**
+   * Every operation of the contract, under its own name only: the way to a
+   * group one of your objects shares a name with, since the object wins at
+   * the root.
+   */
+  readonly contract: AppClient;
+};
+/**
+ * The client with your objects: each one a typed query at the root. An object
+ * named like a contract group takes its place there (the group stays under
+ * `contract`), so a group Standards adds later never changes what your code
+ * reads.
+ */
+type StandardsOf<TObjects extends readonly ObjectBuilderLike[]> = Omit<Standards, keyof ObjectsOf<TObjects>> & ObjectsOf<TObjects>;
+/**
+ * A client in a server that embeds Standards: the same client, plus `as` to
+ * name who acts. Absent over HTTP, where the identity is the API key's.
+ */
+type ActingStandards<S> = S & {
+  /**
+   * The same client, every call acting as `actor`: an actor id, or `"system"`
+   * for the workspace's system actor. Permissions and visibility are that
+   * actor's; the actor the context implies, if any, is recorded as the one
+   * who triggered the call. Without `as`, a call acts as the context implies:
+   * the request's user, the job's enqueuer, the write's author, else the
+   * system.
+   */
+  as(actor: ActorId | "system"): ActingStandards<S>;
+};
+/**
+ * Every call `createStandards` makes is a contract operation (`call`, and
+ * `stream` for an `"events"` one); a records `export()` also
+ * needs an HTTP transport's `postRaw`, and `as` the in-process transport's
+ * `withCaller`.
+ */
+type StandardsTransport = OperationTransport & Partial<Pick<HttpTransport, "postRaw">> & Partial<Pick<InProcessTransport, "withCaller">>;
 /**
- * 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.
+ * The options `createStandards` takes: an API key's HTTP connection
+ * (`baseUrl`, `apiKey`, read from the environment when absent), or a
+ * `transport` of your own (the in-process one in a server that embeds
+ * Standards, `createInProcessTransport`), never both.
  */
-type StandardsConfig = Partial<TransportConfig>;
+type StandardsConfig = Partial<TransportConfig> & {
+  transport?: StandardsTransport;
+};
+declare function createStandards<const TBundles extends readonly AnyBundle[]>(config: StandardsConfig & {
+  transport: InProcessTransport;
+  bundles: TBundles;
+}): ActingStandards<StandardsOf<ObjectsOfBundles<TBundles>>>;
+declare function createStandards(config: StandardsConfig & {
+  transport: InProcessTransport;
+}): ActingStandards<Standards>;
 declare function createStandards<const TBundles extends readonly AnyBundle[]>(config: StandardsConfig & {
   bundles: TBundles;
-}): Standards & ObjectsOf<ObjectsOfBundles<TBundles>>;
+}): StandardsOf<ObjectsOfBundles<TBundles>>;
 declare function createStandards(config?: StandardsConfig): Standards;
-export { PrivateUploadedFile as A, DocumentsTransport as B, UpdateManyEntry as C, CamelCase as D, createRecordsQuery as E, UploadedFile as F, SyncTransport as G, FileInput as H, createFilesApi as I, syncBundle as K, AttachToRecordInput as L, UploadFileInput as M, UploadPrivateFileInput as N, FilesApi as O, UploadPublicFileInput as P, AttachToRecordResult as R, UntypedRecordsQuery as S, UpdateManyResult as T, UploadTimeoutOption as U, createDocumentsApi as V, SyncBundleOptions as W, RecordUpdate as _, StandardsConfig as a, RecordsQuery as b, UsageReportInput as c, CreateManyError as d, CreateManyResult as f, RecordInput as g, FetchResult as h, Standards as i, PublicUploadedFile as j, FilesTransport as k, UsageTransport as l, DeleteManyResult as m, ObjectsOf as n, createStandards as o, DeleteManyError as p, ObjectsOfBundles as r, UsageApi as s, AnyBundle as t, createUsageApi as u, RecordsAggregateOptions as v, UpdateManyError as w, UntypedBuilder as x, RecordsExportOptions as y, DocumentsApi as z };
+export { SyncBundleOptions as A, UntypedBuilder as C, UpdateManyResult as D, UpdateManyError as E, syncBundle as M, createRecordsQuery as O, RecordsQuery as S, UpdateManyEntry as T, RecordInput as _, ObjectsOfBundles as a, RecordsAggregateOptions as b, StandardsOf as c, CreateManyError as d, CreateManyResult as f, RecordCreateOptions as g, FetchResult as h, ObjectsOf as i, SyncTransport as j, CamelCase as k, StandardsTransport as l, DeleteManyResult as m, AnyBundle as n, Standards as o, DeleteManyError as p, BundlesSync as r, StandardsConfig as s, ActingStandards as t, createStandards as u, RecordUpdate as v, UntypedRecordsQuery as w, RecordsExportOptions as x, RecordUpdateOptions as y };