@fluid-app/sites 0.0.0-stage → 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,394 @@
+//#region src/api.d.ts
+/** `fluid.api`. */
+interface SitesApi {
+  /**
+   * Call the Fluid API: `"/orders"` calls `/_fluid/api/v2026-10/orders` on
+   * the site's own origin.
+   *
+   * path - The Member API path, starting with `/`; it may carry a query.
+   * init - The request's options, as for `fetch`.
+   *
+   * Returns the response, whatever its status.
+   * Throws TypeError when the path is not a path under the API, such as an
+   * absolute URL or one that climbs out with `..`.
+   */
+  fetch(path: string, init?: RequestInit): Promise<Response>;
+  /**
+   * `GET` a Fluid API path and parse its JSON.
+   *
+   * path - The Member API path, starting with `/`.
+   * query - Query parameters to add to the path.
+   *
+   * Returns the parsed body.
+   * Throws TypeError for a path as `fetch` refuses it, and FluidRequestError
+   * when the API answers with a status that is not 2xx.
+   */
+  get<T>(path: string, query?: Record<string, string>): Promise<T>;
+}
+/** The path every `fluid.api` call goes under, `/_fluid/api/v2026-10`. */
+declare const API_PATH_PREFIX: string;
+//#endregion
+//#region ../sites-contracts/src/schema.d.ts
+/**
+ * Contracts section 7: `SchemaV1`, a site's `db/schema.json`.
+ *
+ * The gateway reads the schema to check every request, and drivers translate
+ * it into their own storage.
+ */
+/** Any JSON value. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/** `[a-z][a-z0-9_]{0,62}`; not a system column; not starting with "_" or "pg_". */
+type Name = string;
+//#endregion
+//#region ../sites-contracts/src/query.d.ts
+type Row = Record<Name, Value>;
+type Value = string | number | boolean | null | JsonValue;
+/** The answer to a `DbRequestV1`, whatever the HTTP status. */
+interface DbResponseV1 {
+  data: Row[] | null;
+  count?: number;
+  error: DbError | null;
+}
+type DbErrorCode = "validation" | "rule_denied" | "quota_exceeded" | "unique_violation" | "timeout" | "unavailable" | "no_database";
+interface DbError {
+  code: DbErrorCode;
+  message: string;
+  details?: JsonValue;
+}
+//#endregion
+//#region ../sites-contracts/src/access.d.ts
+/** How a viewer relates to a site. `other_company` is V2; phase 014 adds "editor". */
+type ViewerRelation = "owner" | "admin" | "member" | "other_company";
+/** The person a request is made for. */
+interface Viewer {
+  userId: string;
+  name: string;
+  avatarUrl: string | null;
+  /** The viewer's member in the site's company, or null. */
+  memberId: string | null;
+  relation: ViewerRelation;
+}
+//#endregion
+//#region ../sites-contracts/src/sdk.d.ts
+/** The answer to `GET /_fluid/me`. */
+interface Me {
+  viewer: (Viewer & {
+    fields: Record<string, unknown>;
+  }) | null;
+  /** Null unless the decision is allow (section 1). */
+  site: {
+    id: string;
+    handle: string;
+    name: string;
+    visibility: "public" | "private";
+    companyName: string;
+  } | null;
+  scopes: string[];
+  /** The visit's FairShare credit: the sharer's, else the owner's, else "home"; null unless the decision is allow. */
+  credit: string | null;
+  /** The company's primary storefront origin, such as "https://yoli.com". */
+  storefrontUrl: string;
+  /** V1: the storefront origins that may frame the site and send it a port. */
+  shellOrigins: string[];
+}
+/** A thenable: awaiting it sends one `DbRequestV1` and resolves `{ data, error, count }`. */
+interface QueryBuilder extends PromiseLike<DbResponseV1> {
+  /** "a,b" or "*". */
+  select(columns?: string, opts?: {
+    count?: "exact";
+  }): QueryBuilder;
+  insert(rows: Row | Row[]): QueryBuilder;
+  update(set: Row): QueryBuilder;
+  delete(): QueryBuilder;
+  eq(column: string, value: Value): QueryBuilder;
+  neq(column: string, value: Value): QueryBuilder;
+  gt(column: string, value: Value): QueryBuilder;
+  gte(column: string, value: Value): QueryBuilder;
+  lt(column: string, value: Value): QueryBuilder;
+  lte(column: string, value: Value): QueryBuilder;
+  in(column: string, values: Value[]): QueryBuilder;
+  is(column: string, value: null): QueryBuilder;
+  like(column: string, pattern: string): QueryBuilder;
+  ilike(column: string, pattern: string): QueryBuilder;
+  not(column: string, op: string, value: Value): QueryBuilder;
+  /** "a.eq.1,b.gt.2". */
+  or(filters: string): QueryBuilder;
+  match(values: Row): QueryBuilder;
+  order(column: string, opts?: {
+    ascending?: boolean;
+    nullsFirst?: boolean;
+  }): QueryBuilder;
+  limit(count: number): QueryBuilder;
+  range(from: number, to: number): QueryBuilder;
+  single(): PromiseLike<{
+    data: Row | null;
+    error: DbError | null;
+  }>;
+  maybeSingle(): PromiseLike<{
+    data: Row | null;
+    error: DbError | null;
+  }>;
+}
+/** The error a Supabase method this SDK leaves out throws, naming the method. */
+declare const NOT_SUPPORTED: "not_supported";
+//#endregion
+//#region src/auth.d.ts
+/** `fluid.auth`. */
+interface SitesAuth {
+  /**
+   * Read `GET /_fluid/me` on the site's own origin: the viewer, the site,
+   * the scopes, the visit's credit and the shell origins. It waits for the
+   * first shell token, or three seconds, then asks as a guest.
+   *
+   * Returns the answer.
+   * Throws FluidRequestError when `/_fluid/me` answers with a status that is
+   * not 2xx, such as 404 `not_found`.
+   */
+  me(): Promise<Me>;
+  /**
+   * Ask the shell to send the visitor to the storefront's sign-in, and back.
+   * The shell does it only when a click is behind it. With no shell, it does
+   * nothing and logs a warning.
+   *
+   * opts - `returnTo`, the frame path to come back to; the address bar's path when left out.
+   *
+   * Returns nothing.
+   */
+  signIn(opts?: {
+    returnTo?: string;
+  }): void;
+  /**
+   * Ask the shell to open the Passport, which holds the sign-out. With no
+   * shell, it does nothing and logs a warning. V1 ignores `everywhere`.
+   *
+   * opts - `everywhere`, for V2.
+   *
+   * Returns a promise that resolves once the message is posted.
+   */
+  signOut(opts?: {
+    everywhere?: boolean;
+  }): Promise<void>;
+}
+//#endregion
+//#region src/cart.d.ts
+/**
+ * How long a cart call waits for its `cart_result` before it rejects. The
+ * shell answers once FairShare's own call settles, which waits up to three
+ * seconds for FairShare to start and then for the storefront's API; thirty
+ * seconds is well past both, and a shell that never answers (one without the
+ * relay, or a port replaced mid-call) does not leave the call pending forever.
+ */
+declare const CART_RESULT_TIMEOUT_MS = 30000;
+/** `fluid.cart`. Every argument is FairShare's own, passed through unchanged. */
+interface SitesCart {
+  /**
+   * Add to the cart: FairShare's `addCartItems`.
+   *
+   * args - `addCartItems`'s arguments, such as `[{ variant_id: 501, quantity: 1 }]`.
+   *
+   * Returns a promise of what `addCartItems` resolved, usually the cart.
+   * Rejects with an Error when there is no shell, the shell reports a failure,
+   * or no answer comes within thirty seconds.
+   */
+  add(...args: unknown[]): Promise<unknown>;
+  /**
+   * Change quantities: FairShare's `updateCartItems`.
+   *
+   * args - `updateCartItems`'s arguments.
+   *
+   * Returns a promise of what `updateCartItems` resolved.
+   * Rejects as `add` does.
+   */
+  update(...args: unknown[]): Promise<unknown>;
+  /**
+   * Remove a line: FairShare's `removeCartItemById`.
+   *
+   * args - `removeCartItemById`'s arguments, such as the cart item id.
+   *
+   * Returns a promise of what `removeCartItemById` resolved.
+   * Rejects as `add` does.
+   */
+  remove(...args: unknown[]): Promise<unknown>;
+  /**
+   * Read the current cart.
+   *
+   * Returns a promise of the cart.
+   * Rejects as `add` does.
+   */
+  get(): Promise<unknown>;
+  /**
+   * Open the cart drawer in the shell. A failure is logged, never thrown.
+   *
+   * Returns nothing.
+   */
+  open(): void;
+  /**
+   * Close the cart drawer in the shell. A failure is logged, never thrown.
+   *
+   * Returns nothing.
+   */
+  close(): void;
+  /**
+   * Open checkout. It navigates the shell, not the frame. A failure is
+   * logged, never thrown.
+   *
+   * Returns nothing.
+   */
+  checkout(): void;
+  /**
+   * Listen for each change to the cart the shell reports.
+   *
+   * listener - Called with the cart as FairShare's `onCartChange` gave it.
+   *
+   * Returns a function that stops the listener.
+   */
+  onChange(listener: (cart: unknown) => void): () => void;
+}
+//#endregion
+//#region src/db/builder.d.ts
+/** `fluid.db`. */
+interface SitesDb {
+  /**
+   * Start a query on one of the site's tables.
+   *
+   * table - The table's name in the site's schema.
+   *
+   * Returns a builder; awaiting it sends one request.
+   */
+  from(table: string): QueryBuilder;
+}
+/** What `single()` and `maybeSingle()` resolve. */
+interface SingleResponse {
+  data: Row | null;
+  error: DbError | null;
+}
+//#endregion
+//#region src/fn.d.ts
+/** `fluid.fn`. */
+interface SitesFn {
+  /**
+   * Call one of the site's server functions: `"rsvp"` calls
+   * `/_fluid/fn/rsvp` on the site's own origin, as the viewer.
+   *
+   * name - The function's name, such as `rsvp`.
+   * init - The request's options, as for `fetch`.
+   *
+   * Returns the response, whatever its status; in V1, 404
+   * `fn_not_available`.
+   * Throws TypeError when the name is not a function name, so a call never
+   * leaves `/_fluid/fn/`.
+   */
+  fetch(name: string, init?: RequestInit): Promise<Response>;
+}
+//#endregion
+//#region src/shell/go.d.ts
+/** A site router's listener for `go`: the frame path and the fragment, or null. */
+type GoListener = (path: string, hash: string | null) => void;
+//#endregion
+//#region src/shell/history.d.ts
+/** `fluid.history`: how a single-page app follows Back and Forward. */
+interface SitesHistory {
+  /**
+   * Let the site's router follow Back, Forward and the shell's re-syncs.
+   * While a listener is registered, the SDK calls it instead of reloading
+   * the frame with `location.replace`. The listener moves the router to the
+   * path, with `pushState` or `replaceState`; neither adds an entry.
+   *
+   * listener - Called with the frame path, such as "/events/42?tab=2", and
+   *            the fragment, such as "#agenda", or null.
+   *
+   * Examples
+   *
+   *   fluid.history.onGo((path, hash) => router.navigate(path + (hash ?? "")));
+   *
+   * Returns a function that removes the listener.
+   */
+  onGo(listener: GoListener): () => void;
+}
+//#endregion
+//#region src/storefront.d.ts
+/** `fluid.storefront`. */
+interface SitesStorefront {
+  /**
+   * Build the storefront address of a path, carrying the visit's credit:
+   * the credit from the shell, else `/_fluid/me`'s. It waits for the first
+   * shell token, or three seconds, as every `/_fluid/*` call does.
+   *
+   * path - A storefront path, such as `/shop` or `/products/tea?size=2`.
+   *
+   * Examples
+   *
+   *   await fluid.storefront.url("/shop")
+   *   # => "https://yoli.com/janedoe/shop"
+   *
+   * Returns the absolute address; with no credit, or `home`, the path has no
+   * credit prefix.
+   * Throws TypeError when the path leaves the storefront, such as
+   * `https://other.test/shop`.
+   * Throws Error when `/_fluid/me` gives no storefront address.
+   */
+  url(path: string): Promise<string>;
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * The error the SDK throws when `/_fluid/*` answers with a status that is not
+ * 2xx, such as 401 `sign_in_required` or 403 `scope_not_granted`.
+ */
+declare class FluidRequestError extends Error {
+  /** The HTTP status. */
+  readonly status: number;
+  /** The body's `error` code, such as `scope_not_granted`, or null when there is none. */
+  readonly code: string | null;
+  /** The parsed JSON body, or null when the body is not JSON. */
+  readonly body: unknown;
+  constructor(status: number, code: string | null, body: unknown);
+  /**
+   * Read a failed response into an error.
+   *
+   * response - A response whose status is not 2xx.
+   *
+   * Returns the error, carrying the body's `error` code when there is one.
+   */
+  static fromResponse(response: Response): Promise<FluidRequestError>;
+}
+/**
+ * The error a Supabase method that `fluid.db` leaves out throws, such as
+ * `upsert`, `rpc` or a join, so the caller learns at once which one it was
+ * (contracts section 11).
+ */
+declare class NotSupportedError extends Error {
+  /** Always `not_supported`. */
+  readonly code: typeof NOT_SUPPORTED;
+  /** The method or feature that is not supported, such as `upsert`. */
+  readonly method: string;
+  constructor(method: string);
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * The SDK: `fluid.auth`, `fluid.api`, `fluid.db`, `fluid.fn`, `fluid.cart`,
+ * `fluid.history` and `fluid.storefront`.
+ */
+interface Fluid {
+  /** Who is here. */
+  auth: SitesAuth;
+  /** The Fluid API, as the viewer, within the site's grants. */
+  api: SitesApi;
+  /** The site's database, Supabase-style. */
+  db: SitesDb;
+  /** The site's own server functions; in V1 each answers 404 `fn_not_available`. */
+  fn: SitesFn;
+  /** The storefront's cart: FairShare in the shell, with FairShare's own arguments. */
+  cart: SitesCart;
+  /** Back and Forward for a single-page app's router, in a V1 frame. */
+  history: SitesHistory;
+  /** Storefront addresses that carry the visit's FairShare credit. */
+  storefront: SitesStorefront;
+}
+/** The SDK, also at `window.fluid`. */
+declare const fluid: Fluid;
+//#endregion
+export { API_PATH_PREFIX, CART_RESULT_TIMEOUT_MS, type DbError, type DbResponseV1, Fluid, FluidRequestError, type GoListener, type Me, NotSupportedError, type QueryBuilder, type Row, type SingleResponse, type SitesApi, type SitesAuth, type SitesCart, type SitesDb, type SitesFn, type SitesHistory, type SitesStorefront, type Value, fluid };