palbase 0.0.0-stage → 0.1.0

package/types/internal/src/modules/realtime.d.ts

@@ -0,0 +1,326 @@
+import { type Reply, type Transport } from '../transport.js';
+export type BroadcastAccepted = {
+    /**
+     * The events published.
+     */
+    accepted: number;
+};
+export type BroadcastBatch = {
+    /**
+     * 1 to 100 events.
+     */
+    messages: BroadcastMessage[];
+};
+export type BroadcastMessage = {
+    /**
+     * One membership the event is for alone: the conn its join was answered with (what a room's machine is told a member is). Omitted, every member hears it.
+     */
+    conn_id?: string;
+    /**
+     * The event's name.
+     */
+    event: string;
+    /**
+     * The event's payload: any JSON.
+     */
+    payload?: unknown;
+    /**
+     * The channel (without the realtime: prefix the socket carries).
+     */
+    topic: string;
+};
+export type ChannelDeclaration = {
+    /**
+     * The channels, in the order they are matched.
+     */
+    channels: ChannelRule[];
+};
+export type ChannelRule = {
+    /**
+     * owner: the pattern's one {name} is the joining user, who may do everything; public: any signed-in user subscribes, with the rights below.
+     */
+    kind: "owner" | "public";
+    /**
+     * ':'-separated segments, a {name} segment matching exactly one non-empty segment; 255 bytes at most.
+     */
+    pattern: string;
+    /**
+     * A public channel's subscribers may broadcast on it.
+     */
+    publish?: boolean;
+    /**
+     * A public channel's subscribers receive its state.
+     */
+    state_read?: boolean;
+    /**
+     * A public channel's subscribers may write its state.
+     */
+    state_write?: boolean;
+};
+export type ChannelSubscribers = {
+    /**
+     * The channel.
+     */
+    name: string;
+    /**
+     * Its subscribers now: the memberships on it, over every replica.
+     */
+    subscribers: number;
+};
+export type ErrorResponse = {
+    /**
+     * Machine-readable error code (snake_case)
+     */
+    error: string;
+    /**
+     * Human-readable explanation
+     */
+    error_description: string;
+    /**
+     * Correlation ID for log/audit lookup
+     */
+    request_id: string;
+    /**
+     * Seconds to wait before retrying; present on a refusal that ends with time.
+     */
+    retry_after?: number;
+    /**
+     * HTTP status code (mirrors the response status)
+     */
+    status: number;
+};
+export type PlatformLimits = {
+    /**
+     * Channels one connection may be on; 0: no ceiling.
+     */
+    max_channels_per_connection: number;
+    /**
+     * Connections a project may hold open at once; 0: no ceiling.
+     */
+    max_connections: number;
+    /**
+     * Broadcasts and state writes per second; 0: no ceiling.
+     */
+    max_events_per_second: number;
+    /**
+     * Channel joins per second; 0: no ceiling.
+     */
+    max_joins_per_second: number;
+};
+export type RealtimeLimits = {
+    /**
+     * Channels one connection may be on; null: the platform's.
+     */
+    max_channels_per_connection?: number | null;
+    /**
+     * Connections open at once; null: the platform's.
+     */
+    max_connections?: number | null;
+    /**
+     * Broadcasts and state writes per second; null: the platform's.
+     */
+    max_events_per_second?: number | null;
+    /**
+     * Channel joins per second; null: the platform's.
+     */
+    max_joins_per_second?: number | null;
+    platform?: PlatformLimits;
+};
+export type RealtimeLimitsWrite = {
+    /**
+     * Channels one connection may be on; null: the platform's.
+     */
+    max_channels_per_connection?: number | null;
+    /**
+     * Connections open at once; null: the platform's.
+     */
+    max_connections?: number | null;
+    /**
+     * Broadcasts and state writes per second; null: the platform's.
+     */
+    max_events_per_second?: number | null;
+    /**
+     * Channel joins per second; null: the platform's.
+     */
+    max_joins_per_second?: number | null;
+};
+export type RealtimeStats = {
+    /**
+     * The rows' bucket.
+     */
+    bucket: "hour" | "day";
+    limits: StatsLimits;
+    now: StatsNow;
+    /**
+     * The measured buckets that overlap the window, oldest first. A bucket nobody measured is absent: zero for a counter, no value for a gauge.
+     */
+    rows: StatsRow[];
+    /**
+     * The window read, in seconds.
+     */
+    window_seconds: number;
+};
+export type StateApplied = {
+    /**
+     * The operations applied.
+     */
+    applied: number;
+};
+export type StateBatch = {
+    /**
+     * 1 to 100 operations.
+     */
+    ops: StateOp[];
+};
+export type StateOp = {
+    /**
+     * Remove the entry instead.
+     */
+    delete?: boolean;
+    /**
+     * The entry's key.
+     */
+    key: string;
+    /**
+     * The channel.
+     */
+    topic: string;
+    /**
+     * The entry's value: any JSON (16 KiB at most). Absent with delete.
+     */
+    value?: unknown;
+};
+export type StatsLimits = {
+    /**
+     * The connections the project may hold open at once — its own limit under the platform's (PUT /realtime/limits); null when there is none.
+     */
+    connections: number | null;
+};
+/**
+ * What the project holds this moment, over every replica — asked of each replica when read, never a stored sample. Gauges.
+ */
+export type StatsNow = {
+    /**
+     * Channels with at least one subscriber now — a channel with subscribers on two replicas is one. The platform's channels the SDKs join (roles:<ref>:<user_id>, flags:<ref>) are among them.
+     */
+    channels: number;
+    /**
+     * Sockets open now.
+     */
+    connections: number;
+    /**
+     * The 10 channels with the most subscribers now, the most first (ties by name).
+     */
+    top_channels: ChannelSubscribers[];
+};
+/**
+ * One measured bucket. peak_connections is a gauge (a bucket's highest); the rest are counters (a bucket's total).
+ */
+export type StatsRow = {
+    /**
+     * Counter: broadcasts published on the project's channels — by its clients, its server, the platform's notices — once each, however many received them.
+     */
+    broadcasts: number;
+    /**
+     * The bucket's start, Unix milliseconds: a UTC hour or day.
+     */
+    bucket_ms: number;
+    /**
+     * Counter: sockets opened.
+     */
+    connections_opened: number;
+    /**
+     * Counter: sockets refused (429) at the project's connection limit or its used-up realtime quota.
+     */
+    connections_refused: number;
+    /**
+     * Counter: frames delivered to the project's sockets — a broadcast as each subscriber received it, a state snapshot or diff. What the meter counts as realtime.messages.
+     */
+    messages_delivered: number;
+    /**
+     * Gauge: the most sockets the project held at once in the bucket — each minute's census summed over every replica, or one replica's own most between two censuses; never above the true peak, and 0 when no census saw one open.
+     */
+    peak_connections: number;
+    /**
+     * Counter: presence (ephemeral) entries written new: a membership's first write of a key, or its first since it removed it.
+     */
+    presence_joins: number;
+    /**
+     * Counter: presence entries removed — by their writer, with its membership, or by the reaper after its replica died.
+     */
+    presence_leaves: number;
+};
+/** Palbase Realtime */
+export declare function client(t: Transport): {
+    /**
+     * Broadcast as the server
+     *
+     * Publishes events on the project's channels, to every subscriber on every replica, as the project's server (1 to 100 events). Delivered at most once, like every broadcast.
+     */
+    broadcast(input: {
+        body: BroadcastBatch; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<202, BroadcastAccepted>>;
+    /**
+     * Read the channel declaration
+     *
+     * The project's channels, in the order they are matched: the first pattern that matches a channel decides it.
+     */
+    getChannels(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, ChannelDeclaration>>;
+    /**
+     * Declare the channels
+     *
+     * Replaces the project's channel declaration, in its order (100 at most). A pattern is ':'-separated segments; a {name} segment matches exactly one. `owner`: the pattern's one {name} must be the joining user, who may do everything on it. `public`: any signed-in user of the project subscribes, and may publish and read or write state as declared. A channel no pattern matches belongs to no one. roles:, flags:, messaging: and debug: are the platform's. Open sockets are decided again within a heartbeat.
+     */
+    putChannels(input: {
+        body: ChannelDeclaration; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, ChannelDeclaration>>;
+    /**
+     * Read the limits
+     *
+     * The limits the project set for its clients (null: the platform's), and the platform's, which they may only go under.
+     */
+    getLimits(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, RealtimeLimits>>;
+    /**
+     * Set the limits
+     *
+     * Sets the limits the project holds its clients to: connections open at once, events (broadcasts and state writes) and joins per second, channels per connection. null is the platform's; a value above the platform's has no effect beyond it.
+     */
+    putLimits(input: {
+        body: RealtimeLimitsWrite; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, RealtimeLimits>>;
+    /**
+     * Write state as the server
+     *
+     * Writes or removes entries of the project's channels' state, as the project's server (1 to 100 operations): durable entries, read by every subscriber with state access as a diff. A write past a channel's budget is refused (422) and the operations before it stay applied.
+     */
+    writeState(input: {
+        body: StateBatch; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, StateApplied>>;
+    /**
+     * Read the realtime stats
+     *
+     * The project's realtime, measured — for its charts.
+     *
+     * `now` is what it holds this moment: every replica is asked when this is read and all must answer; a replica that is alive and silent (one that just died, for up to 15 seconds) makes it a 503 to retry, never a smaller number.
+     *
+     * `rows` are the window's buckets (UTC hours, or days), from what realtime measured as it ran: each replica counts in memory and adds its counts to the hour once a minute — a replica that dies loses at most its last minute — and the leader counts every replica's sockets once a minute for the peak. `peak_connections` is a gauge; `messages_delivered`, `broadcasts`, `presence_joins`, `presence_leaves`, `connections_opened` and `connections_refused` are counters. Hours are kept 91 days, then forgotten; they go with the project.
+     *
+     * `limits.connections` is the connection limit in force, for a limit line.
+     */
+    getStats(input?: {
+        query?: {
+            window_seconds?: number; /** The rows' bucket: hour or day. Absent: hour up to a window of two days, day beyond. */
+            bucket?: "hour" | "day";
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, RealtimeStats>>;
+};
+export type Client = ReturnType<typeof client>;

package/types/internal/src/modules/secrets.d.ts

@@ -0,0 +1,275 @@
+import { type Reply, type Transport } from '../transport.js';
+/**
+ * Every secret of an environment with its value.
+ */
+export type EnvironmentValues = {
+    environment: "development" | "production";
+    /**
+     * Each secret's current value, by name.
+     */
+    values: {
+        [key: string]: string;
+    };
+    /**
+     * Each secret's current version, by name.
+     */
+    versions: {
+        [key: string]: number;
+    };
+};
+export type ErrorResponse = {
+    /**
+     * Machine-readable error code (snake_case)
+     */
+    error: string;
+    /**
+     * Human-readable explanation
+     */
+    error_description: string;
+    /**
+     * Correlation ID for log/audit lookup
+     */
+    request_id: string;
+    /**
+     * Seconds to wait before retrying; present on a refusal that ends with time.
+     */
+    retry_after?: number;
+    /**
+     * HTTP status code (mirrors the response status)
+     */
+    status: number;
+};
+/**
+ * A secret, without its value.
+ */
+export type Secret = {
+    created_at: string;
+    environment: "development" | "production";
+    /**
+     * An environment-variable name.
+     */
+    name: string;
+    updated_at: string;
+    /**
+     * The current version.
+     */
+    version: number;
+};
+/**
+ * One read or write of the project's secrets.
+ */
+export type SecretAuditEntry = {
+    action: "list" | "read" | "read_all" | "write" | "rollback" | "delete" | "versions";
+    /**
+     * When it happened.
+     */
+    at: string;
+    environment: "development" | "production";
+    id: string;
+    /**
+     * The id of the key that made the request.
+     */
+    key_id: string;
+    /**
+     * The secret, when the action names one.
+     */
+    name?: string;
+    request_id: string;
+    /**
+     * The version read or written, when there is one.
+     */
+    version?: number;
+};
+/**
+ * A page of the audit trail, newest first.
+ */
+export type SecretAuditPage = {
+    entries: SecretAuditEntry[];
+    /**
+     * The cursor of the next page; absent on the last page.
+     */
+    next_cursor?: string;
+};
+/**
+ * A page of an environment's secrets, by name.
+ */
+export type SecretPage = {
+    /**
+     * The cursor of the next page; absent on the last page.
+     */
+    next_cursor?: string;
+    secrets: Secret[];
+};
+/**
+ * The version to go back to.
+ */
+export type SecretRollback = {
+    version: number;
+};
+/**
+ * A secret's current value.
+ */
+export type SecretValue = {
+    created_at: string;
+    environment: "development" | "production";
+    name: string;
+    updated_at: string;
+    /**
+     * The value, as written.
+     */
+    value: string;
+    version: number;
+};
+/**
+ * One of a secret's versions, without its value.
+ */
+export type SecretVersion = {
+    created_at: string;
+    /**
+     * The id of the key that wrote it.
+     */
+    created_by: string;
+    /**
+     * Whether it is the secret's value now.
+     */
+    current: boolean;
+    version: number;
+};
+/**
+ * A page of a secret's versions, newest first.
+ */
+export type SecretVersionPage = {
+    /**
+     * The cursor of the next page; absent on the last page.
+     */
+    next_cursor?: string;
+    versions: SecretVersion[];
+};
+/**
+ * A secret's new value.
+ */
+export type SecretWrite = {
+    /**
+     * The value, 64 KiB at most.
+     */
+    value: string;
+};
+/** Palbase Secrets */
+export declare function client(t: Transport): {
+    /**
+     * List the audit trail
+     *
+     * Every read and write of the project's secrets, newest first, with the key that made it and the request id. Narrow it to an environment, and to a secret's name.
+     */
+    listSecretAudit(input?: {
+        query?: {
+            limit?: number; /** The next_cursor of the previous page. Opaque; omit it for the first page. */
+            cursor?: string; /** Only this environment's entries. */
+            environment?: "development" | "production"; /** Only this secret's entries. */
+            name?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, SecretAuditPage>>;
+    /**
+     * List an environment's secrets
+     *
+     * An environment's secrets by name, with their current version — never their values. The listing is recorded in the audit trail.
+     */
+    listSecrets(input: {
+        path: {
+            environment: "development" | "production";
+        };
+        query?: {
+            limit?: number; /** The next_cursor of the previous page. Opaque; omit it for the first page. */
+            cursor?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, SecretPage>>;
+    /**
+     * Read every value of an environment
+     *
+     * Every secret of the environment with its current value, in one call: what a server reads at startup. The read is recorded in the audit trail.
+     */
+    getEnvironmentValues(input: {
+        path: {
+            environment: "development" | "production";
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, EnvironmentValues>>;
+    /**
+     * Read a secret
+     *
+     * A secret's current value. The read is recorded in the audit trail.
+     */
+    getSecret(input: {
+        path: {
+            environment: "development" | "production"; /** The secret's name: an environment-variable name (A-Z, 0-9 and _, starting with a letter, 128 at most). */
+            name: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, SecretValue>>;
+    /**
+     * Write a secret
+     *
+     * Writes the value as the secret's next version, creating the secret if it is new. Every write is a new version; the old ones stay, to go back to. Emits `secret.changed` (without the value). An environment holds 1000 secrets at most, a value 64 KiB.
+     */
+    putSecret(input: {
+        path: {
+            environment: "development" | "production"; /** The secret's name: an environment-variable name (A-Z, 0-9 and _, starting with a letter, 128 at most). */
+            name: string;
+        };
+        headers?: {
+            "Idempotency-Key"?: string;
+        };
+        body: SecretWrite; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Secret>>;
+    /**
+     * Delete a secret
+     *
+     * Forgets the secret and every version of it. Emits `secret.changed` (without the value).
+     */
+    deleteSecret(input: {
+        path: {
+            environment: "development" | "production"; /** The secret's name: an environment-variable name (A-Z, 0-9 and _, starting with a letter, 128 at most). */
+            name: string;
+        };
+        headers?: {
+            "Idempotency-Key"?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<204, undefined>>;
+    /**
+     * Go back to an earlier version
+     *
+     * Makes an earlier version's value the secret's next version; the history stays whole. Emits `secret.changed` (without the value).
+     */
+    rollbackSecret(input: {
+        path: {
+            environment: "development" | "production"; /** The secret's name: an environment-variable name (A-Z, 0-9 and _, starting with a letter, 128 at most). */
+            name: string;
+        };
+        headers?: {
+            "Idempotency-Key"?: string;
+        };
+        body: SecretRollback; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Secret>>;
+    /**
+     * List a secret's versions
+     *
+     * A secret's versions, newest first, with the key that wrote each — never their values.
+     */
+    listSecretVersions(input: {
+        path: {
+            environment: "development" | "production"; /** The secret's name: an environment-variable name (A-Z, 0-9 and _, starting with a letter, 128 at most). */
+            name: string;
+        };
+        query?: {
+            limit?: number; /** The next_cursor of the previous page. Opaque; omit it for the first page. */
+            cursor?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, SecretVersionPage>>;
+};
+export type Client = ReturnType<typeof client>;