Client and transports.

FlowerClient

Use FlowerClient to call your methods from Node or a browser. Point it at any cluster member, and give it your app's type.

import { FlowerClient, FlowerError } from "@flower-js/sdk/client";
import type counter from "./counter.ts";

const db = new FlowerClient<typeof counter>("http://node-1:7101", {
  queryUrls: ["http://node-1:7101", "http://node-2:7101", "http://node-3:7101"],
  retry: true,
});
try {
  await db.mutate("counter.increment", { id: "visits", by: 1 }, { requestId: "visit-42" });
} catch (error) {
  if (!(error instanceof FlowerError) || !error.failure) throw error;
  console.error(error.failure.code, error.failure.details);
}

Retrying safely

• A timed-out or lost mutation may still have committed. Retry with the same request ID, arguments and expected revision; retry does this for you. Save the request ID first if the process itself may restart.
• Same ID, different body: REQUEST_ID_REUSED. Stale expected revision: REVISION_CONFLICT. Server queue full: 503.
• Aborting stops waiting. It doesn’t undo a commit.
• Old request IDs never run again, even after their results are dropped. See retry retention.
• The client doesn’t move mutations to another member. If the main URL is unreachable, point a client at another one.

Live values

Watches stream a query’s latest value as it changes, over SSE. subscribe keeps one going through disconnects.

import { FlowerClient } from "@flower-js/sdk/client";
import type pizza from "./pizza.ts";

const db = new FlowerClient<typeof pizza>("http://node-1:7101");
const stop = new AbortController();
for await (const { revision, value, reset } of db.subscribe("pizza.board", null, { signal: stop.signal })) {
  console.log(revision, reset, value.orders, value.mushroom);
  // break or stop.abort() releases the subscription.
}

• A watch gives you the latest value, not every change. Intermediate revisions can be skipped. It isn’t an event log.
• Fresh watches read like fresh queries. Replica-local watches can lag, and can go back in time after reconnecting elsewhere; monotonic hides that.
• A redeploy or change of caller identity ends a stream with WATCH_SCOPE_CHANGED, which subscribe treats as a reconnect. Malformed stream data ends it with WATCH_PROTOCOL_ERROR.
• Error events carry the method’s failure, like HTTP errors.
• Each subscriber is authorized on every refresh. Remember that one watched value can combine data from many records.
• There’s no fixed limit on watch count. Memory, sockets and update rate set the practical limit. Slow consumers get batched updates and are eventually closed.

FlowerAdmin

Operator calls live on their own client, which sends the admin token on every request. Keep it out of browsers and application bundles.

import { FlowerAdmin } from "@flower-js/sdk/client";
import { buildBundle } from "@flower-js/sdk/bundle";

const admin = new FlowerAdmin("http://node-1:7101", { adminToken: process.env.FLOWER_ADMIN_TOKEN });
const bundle = await buildBundle("app.ts");
console.log(await admin.deploy(bundle, { requestId: `deploy-${bundle.hash}` }));

admin.partition(name) targets one named database. The other operator methods are documented with their topics: staged deployment, managed keys, partitions and resizing, and retention and transaction closure.

HTTP/2 transport

In Node, use one pooled HTTP/2 transport to share connections across many requests and watches.

import { FlowerClient } from "@flower-js/sdk/client";
import { createHttp2Transport } from "@flower-js/sdk/http2";
import type pizza from "./pizza.ts";

const transport = createHttp2Transport();
try {
  const db = new FlowerClient<typeof pizza>("http://localhost:7101", { fetch: transport.fetch });
  console.log(await db.query("pizza.board"));
} finally {
  await transport.close();
}

• The request timeout covers the whole response, except for SSE, where it covers only the headers.
• No HTTP/1 fallback, redirects or compressed responses. Retries come from the client’s retry option.
• Transport failures throw errors with H2_* codes. After a connection failure, a mutation’s outcome is unknown, so retry it with the same request ID.