@abloatai/transaction 0.38.0 → 0.40.0

package/src/wire/accountResponses.ts

@@ -19,6 +19,9 @@ import { z } from 'zod';
 // response exists to stop withholding.
 import { fieldMetaSchema, relationMetaSchema } from './modelShape.js';
 import { onStaleModeSchema } from '../coordination/schema.js';
+// The price's own vocabulary. A dashboard that restated the tier names or the
+// meter set would be a second definition of what the invoice is computed from.
+import { meterEventSchema, planTierSchema, rateBracketSchema } from './pricing.js';
 import type { SyncDeltaAction } from './delta.js';
 import { deltaSchema } from './delta.js';
 // Kept for the {@link ListEnvelope} references below; `GET /v1/logs`'s own
@@ -325,3 +328,76 @@ export const usageReportResponseSchema = z.object({
   data_freshness_seconds: z.number(),
 });
 export type UsageReportResponse = z.infer<typeof usageReportResponseSchema>;
+
+/**
+ * One meter's month-to-date usage, as a management surface shows it.
+ *
+ * `eventName` is the pricing contract's closed set rather than a free string,
+ * so a surface cannot render a meter the price does not recognise. `billable`
+ * says whether the meter reaches an invoice at all: bootstraps are recorded and
+ * gated but never charged, and a usage table that does not say so reads as a
+ * bill nobody sent.
+ */
+export const meterUsageSchema = z.object({
+  eventName: meterEventSchema,
+  displayName: z.string(),
+  /** Operations counted this period. */
+  total: z.number(),
+  /** Requests behind that total. A commit of 500 operations counts once here. */
+  count: z.number(),
+  /** The plan's monthly allowance for this meter; null where it is ungated. */
+  monthlyMax: z.number().nullable(),
+  billable: z.boolean(),
+});
+export type MeterUsage = z.infer<typeof meterUsageSchema>;
+
+/**
+ * What the period costs, computed once by the server from the pricing contract.
+ *
+ * The client renders these rather than recomputing them. A dashboard that does
+ * its own arithmetic is a second implementation of the price, and the one a
+ * customer reads before they are billed, so it is the copy that has to be
+ * right and the one nothing checks.
+ */
+export const billingSummarySchema = z.object({
+  tier: planTierSchema,
+  /** The tier as it reads on the pricing page. */
+  label: z.string(),
+  /** The monthly floor in USD; null where terms are contractual. */
+  monthlyMinimumUsd: z.number().nullable(),
+  /** Operations the floor already covers, or the hard cap on a capped tier. */
+  includedOps: z.number().nullable(),
+  /** Where the tier stops rather than bills; null on every metered tier. */
+  hardCapOps: z.number().nullable(),
+  /** The daily burst guard; null on every metered tier. */
+  dailyCapOps: z.number().nullable(),
+  /** Every billable meter, collapsed into the one number the price uses. */
+  opsUsed: z.number(),
+  /** The floor or the metered usage, whichever is greater. null = contract. */
+  projectedBillUsd: z.number().nullable(),
+  /** True where the published card is a starting point, not the terms. */
+  contractPriced: z.boolean(),
+  /**
+   * The rate card in force, so a surface can show what the next operation
+   * costs without shipping a copy of the price to the browser.
+   */
+  rateCard: z.array(rateBracketSchema).readonly(),
+});
+export type BillingSummary = z.infer<typeof billingSummarySchema>;
+
+/**
+ * `GET /v1/dashboard/usage-summary` — month-to-date usage and what it costs.
+ *
+ * Distinct from {@link usageReportResponseSchema}, which answers the public
+ * `GET /v1/usage` with daily buckets for a caller doing its own analysis. This
+ * one answers the question a person opens a dashboard to ask: what have I used,
+ * and what will it cost.
+ */
+export const usageSummaryResponseSchema = z.object({
+  plan: planTierSchema,
+  /** Start of the billing period the numbers cover, ISO-8601. */
+  periodStart: z.string(),
+  meters: z.array(meterUsageSchema).readonly(),
+  billing: billingSummarySchema,
+});
+export type UsageSummaryResponse = z.infer<typeof usageSummaryResponseSchema>;

package/src/wire/auth.ts

@@ -11,7 +11,7 @@
  */
 
 import { z } from 'zod';
-import { grantedOperationSchema } from '../auth/capability.js';
+import { capabilityOperationSchema, grantedOperationSchema } from '../auth/capability.js';
 import { syncGroupInputSchema } from '../coordination/schema.js';
 
 /** The participant this session acts as. */
@@ -48,8 +48,25 @@ export const ephemeralKeyRequestSchema = z.object({
   schemaOwnerOrgId: z.string().min(1).optional(),
   /** Narrow the session to these sync groups. */
   syncGroups: z.array(syncGroupInputSchema).readonly().optional(),
-  /** Required least-privilege allowlist. */
-  operations: z.array(grantedOperationSchema).min(1),
+  /**
+   * Least-privilege allowlist, named model by model. For a caller that knows
+   * the schema the session will resolve. Exactly one of this and
+   * {@link ephemeralKeyRequestSchema.shape.activeSchemaOperations} is required.
+   */
+  operations: z.array(grantedOperationSchema).min(1).optional(),
+  /**
+   * The same allowlist expressed as verbs alone, for a caller that CANNOT know
+   * the models: an identity service minting sessions for organizations whose
+   * schemas it does not own has no way to name them, and a grant is checked
+   * against the session's schema at mint time, so naming another schema's
+   * models fails every time.
+   *
+   * The server expands these across the models in the session's active schema
+   * and stores the concrete result, so what lands on the credential is the same
+   * enumerated allowlist as the field above. A verb is granted only where the
+   * model admits it — an immutable model takes `read` and nothing else.
+   */
+  activeSchemaOperations: z.array(capabilityOperationSchema).min(1).optional(),
   /** Lifetime in seconds. Capped by the server's maximum. */
   ttlSeconds: z.number().int().positive().optional(),
   /** A human-readable tag recorded with the key, for debugging. */
@@ -63,6 +80,16 @@ export const ephemeralKeyRequestSchema = z.object({
       'schemaProjectId and schemaOwnerOrgId must be provided together',
     path: ['schemaProjectId'],
   },
+).refine(
+  (request) =>
+    (request.operations === undefined) !== (request.activeSchemaOperations === undefined),
+  {
+    // Exactly one, never both and never neither. Neither would leave the
+    // credential with an empty allowlist, which reads as UNRESTRICTED at the
+    // gate rather than as nothing; both would leave two answers to one question.
+    message: 'provide either operations or activeSchemaOperations, not both',
+    path: ['operations'],
+  },
 );
 export type EphemeralKeyRequest = z.infer<typeof ephemeralKeyRequestSchema>;
 

package/src/wire/dataSourceResponses.ts

@@ -0,0 +1,188 @@
+/**
+ * What the DATASOURCE routes answer with — the connect surface you reach
+ * through `ablo connect` and its verbs: `POST /v1/datasources` (register),
+ * `POST /v1/datasources/validate` (readiness from Ablo's own network),
+ * `POST /v1/datasources/locate` (which plane holds a database),
+ * `GET /v1/datasources` (this plane's registrations), and
+ * `DELETE /v1/datasources` (deregister).
+ *
+ * These are the shapes the server, the CLI, and the dashboard have to agree
+ * on. Before this module each consumer spelled them out again — the server
+ * inline in `c.json({ … })`, the CLI in three separate hand-rolled decoders —
+ * so a renamed field surfaced as `undefined` in a success message, and a
+ * warning the server attached (a replication slot still holding the customer's
+ * write-ahead log) was silently dropped by a reader that never knew the key
+ * existed.
+ *
+ * Reader stance: fields beyond each response's core verdict are OPTIONAL here
+ * even where today's server always sends them. The CLI dials deployments that
+ * skew across releases, and a strict parse would refuse a run that succeeded —
+ * the worst failure class this surface has. The parse still fails loudly on a
+ * body that is not the response at all (a proxy's HTML page, another route's
+ * answer), which is the drift this module exists to catch.
+ */
+
+import { z } from 'zod';
+
+/**
+ * The readiness vocabulary — every invariant the engine's preflights can name
+ * in a failure. ONE definition site: the server's probes type their `item`
+ * against {@link ReadinessItem}, so an item outside this list cannot compile,
+ * and the CLI's plain-language renderer is total over it, so an item added
+ * here fails the CLI build until it has a label. That closed loop is what
+ * stops the vocabulary drifting apart in three files again — the CLI shipped
+ * without a label for `server_version` for exactly that reason.
+ *
+ * On the WIRE `item` stays an open string (see {@link readinessFailureSchema})
+ * so an older reader survives a newer server; this list is the closed set
+ * producers may emit, not a parse constraint.
+ */
+export const READINESS_ITEMS = [
+  'server_version',
+  'wal_level',
+  'publication',
+  'replication_role',
+  'replica_identity',
+  'table_select',
+  'write_role',
+  'row_security',
+  'database_privileges',
+  'schema_privileges',
+  'table_ownership',
+  'idempotency_ledger',
+  'table_privileges',
+  'logical_marker',
+  'publication_drift',
+] as const;
+export type ReadinessItem = (typeof READINESS_ITEMS)[number];
+
+const READINESS_ITEM_SET: ReadonlySet<string> = new Set(READINESS_ITEMS);
+
+/** Whether a wire `item` is one this build's vocabulary knows — the reader's
+ *  branch between a labelled rendering and the raw-name fallback. */
+export function isReadinessItem(item: string): item is ReadinessItem {
+  return READINESS_ITEM_SET.has(item);
+}
+
+/** The advisory vocabulary — recommendations that never block a registration. */
+export const READINESS_ADVISORY_ITEMS = ['slot_failover'] as const;
+export type ReadinessAdvisoryItem = (typeof READINESS_ADVISORY_ITEMS)[number];
+
+/**
+ * One failing readiness invariant, with its fix in hand. `item` names the
+ * invariant — see {@link READINESS_ITEMS} for the set a producer may emit,
+ * and why the wire keeps it open here. `fix` carries the exact statement or
+ * step that resolves it; `actual` the observed value, when one exists.
+ */
+export const readinessFailureSchema = z.object({
+  item: z.string(),
+  actual: z.string().optional(),
+  fix: z.string(),
+});
+export type ReadinessFailure = z.infer<typeof readinessFailureSchema>;
+
+/** A recommendation that rides beside the verdict without changing it. */
+export const readinessAdvisorySchema = z.object({
+  item: z.string(),
+  recommendation: z.string(),
+});
+export type ReadinessAdvisory = z.infer<typeof readinessAdvisorySchema>;
+
+/**
+ * One registration, as the routes report it — the credential-free projection
+ * of a data source. This is the row of `GET /v1/datasources` and the success
+ * body of `POST /v1/datasources`. Everything here is safe to display: the
+ * credential is decomposed at registration and never returns.
+ */
+export const datasourceSummarySchema = z
+  .object({
+    /** Asserted when present; optional because an older deployment may omit
+     *  the discriminator, and refusing its answer would refuse a run that
+     *  succeeded. */
+    object: z.literal('datasource').optional(),
+    id: z.string().optional(),
+    /** How writes reach the database: Ablo's own scoped role, or the signed
+     *  endpoint fallback. Unknown future kinds degrade to absent rather than
+     *  failing the parse. */
+    connection: z.enum(['direct', 'endpoint']).optional().catch(undefined),
+    /** host:port of the connection — safe to display. */
+    host: z.string().optional(),
+    database: z.string().optional(),
+    schema: z.string().optional(),
+    display_name: z.string().optional(),
+    status: z.string().optional(),
+    livemode: z.boolean().optional(),
+  })
+  .loose();
+export type DatasourceSummary = z.infer<typeof datasourceSummarySchema>;
+
+/** `GET /v1/datasources` — every registration on the calling key's plane. */
+export const datasourceListResponseSchema = z.object({
+  object: z.literal('list'),
+  data: z.array(datasourceSummarySchema).readonly(),
+});
+export type DatasourceListResponse = z.infer<typeof datasourceListResponseSchema>;
+
+/**
+ * `POST /v1/datasources/validate` — replication readiness as judged from
+ * Ablo's own network, the network replication actually runs from.
+ *
+ * `reachable` and `ready` are the verdict and always present; `reason` carries
+ * the driver's words when the engine couldn't reach the host either; `failures`
+ * is the checklist, each entry with its fix.
+ */
+export const datasourceValidationResponseSchema = z.object({
+  object: z.literal('datasource_validation').optional(),
+  connection: z.enum(['direct', 'endpoint']).optional().catch(undefined),
+  reachable: z.boolean(),
+  ready: z.boolean(),
+  reason: z.string().optional(),
+  failures: z.array(readinessFailureSchema).readonly(),
+  advisories: z.array(readinessAdvisorySchema).readonly().optional(),
+});
+export type DatasourceValidationResponse = z.infer<typeof datasourceValidationResponseSchema>;
+
+/**
+ * `POST /v1/datasources/locate` — which plane already holds a database.
+ * A targeted lookup, not an enumeration: the caller must hold the connection
+ * string, and the answer is only the holding plane. `held: null` means no
+ * other plane holds it and a registration would not conflict.
+ */
+export const datasourceLocationResponseSchema = z.object({
+  object: z.literal('datasource_location').optional(),
+  held: z
+    .object({
+      project: z.string().nullable(),
+      branch: z.string(),
+    })
+    .nullable(),
+});
+export type DatasourceLocationResponse = z.infer<typeof datasourceLocationResponseSchema>;
+
+/**
+ * `DELETE /v1/datasources` — what the deregistration let go of.
+ *
+ * `replication_slot` is the part a reader must not drop: when Ablo stopped
+ * reading but the slot survived (`released: false`), that slot is still on the
+ * customer's database holding their write-ahead log, and `remove_with` carries
+ * the statement that removes it. Nothing else will ever release it.
+ */
+export const datasourceDisconnectedResponseSchema = z.object({
+  object: z.literal('datasource_disconnected').optional(),
+  organization_id: z.string().optional(),
+  environment: z.string().optional(),
+  cleared: z.object({
+    direct: z.boolean(),
+    endpoints: z.number(),
+  }),
+  replication_slot: z
+    .object({
+      slot: z.string(),
+      released: z.boolean(),
+      detail: z.string().optional(),
+      remove_with: z.string().optional(),
+      warning: z.string().optional(),
+    })
+    .optional(),
+});
+export type DatasourceDisconnectedResponse = z.infer<typeof datasourceDisconnectedResponseSchema>;

package/src/wire/index.ts

@@ -274,6 +274,9 @@ export {
   logEventSchema,
   usageBucketSchema,
   usageReportResponseSchema,
+  meterUsageSchema,
+  billingSummarySchema,
+  usageSummaryResponseSchema,
   controlKeySchema,
   controlKeyListResponseSchema,
   keyMintedResponseSchema,
@@ -290,12 +293,42 @@ export type {
   LogEvent,
   UsageBucket,
   UsageReportResponse,
+  MeterUsage,
+  BillingSummary,
+  UsageSummaryResponse,
   ControlKey,
   ControlKeyListResponse,
   KeyMintedResponse,
   KeyRevokedResponse,
 } from './accountResponses.js';
 
+// The datasource routes' responses — the `ablo connect` surface: register,
+// validate, locate, list, deregister. What the server, the CLI, and the
+// dashboard agree on.
+export {
+  READINESS_ITEMS,
+  READINESS_ADVISORY_ITEMS,
+  isReadinessItem,
+  readinessFailureSchema,
+  readinessAdvisorySchema,
+  datasourceSummarySchema,
+  datasourceListResponseSchema,
+  datasourceValidationResponseSchema,
+  datasourceLocationResponseSchema,
+  datasourceDisconnectedResponseSchema,
+} from './dataSourceResponses.js';
+export type {
+  ReadinessItem,
+  ReadinessAdvisoryItem,
+  ReadinessFailure,
+  ReadinessAdvisory,
+  DatasourceSummary,
+  DatasourceListResponse,
+  DatasourceValidationResponse,
+  DatasourceLocationResponse,
+  DatasourceDisconnectedResponse,
+} from './dataSourceResponses.js';
+
 // The inbound socket surface: every frame the server can send, and how each
 // one's payload is validated.
 export {

package/src/wire/pricing.ts

@@ -0,0 +1,41 @@
+/**
+ * The pricing vocabulary that crosses the wire: the tier names, the meter
+ * names, and the shape of one rate-card step. Account responses carry these,
+ * so they live in the dependency-free wire layer; the pricing contract
+ * (`../pricing.ts`) derives the rate card, the plans, and the bill arithmetic
+ * from them and re-exports them for its consumers.
+ */
+import { z } from 'zod';
+
+export const planTierSchema = z.enum(['free', 'scale', 'enterprise']);
+export type PlanTier = z.infer<typeof planTierSchema>;
+
+/**
+ * Every meter the engine records, over any transport. This is the closed set
+ * behind the loose `eventName` strings that `UsageRecorder` and the quota gate
+ * pass around.
+ *
+ * Recording and pricing are separate questions. A meter exists so usage can be
+ * gated and attributed; whether it reaches an invoice is `METER_EVENT_AXIS`.
+ * Bootstraps are recorded and quota-gated but deliberately unpriced: a bootstrap
+ * is what a client does once to become useful, and charging for it would price
+ * the act of connecting.
+ */
+export const meterEventSchema = z.enum([
+  'api.commit_ops',
+  'api.model_reads',
+  'api.claim_creates',
+  'api.bootstraps',
+]);
+export type MeterEvent = z.infer<typeof meterEventSchema>;
+
+/**
+ * One step of the rate card. `throughOps` is the cumulative ceiling the rate
+ * applies up to, and `null` marks the final, unbounded step. Rates are marginal:
+ * crossing a ceiling reprices the operations above it, never the ones below.
+ */
+export const rateBracketSchema = z.object({
+  throughOps: z.number().int().positive().nullable(),
+  usdPerMillionOps: z.number().nonnegative(),
+});
+export type RateBracket = z.infer<typeof rateBracketSchema>;