rivetkit 2.3.19 → 2.3.21

package/dist/browser/client.d.ts

@@ -1,6 +1,7 @@
 import * as _rivetkit_rivetkit_wasm from '@rivetkit/rivetkit-wasm';
 import { z as z$2 } from 'zod';
 import z$1, { z } from 'zod/v4';
+import { Rivet } from '@rivetkit/engine-api-full';
 import { Context, Handler, Hono } from 'hono';
 import { UniversalWebSocket } from '@rivetkit/virtual-websocket';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -176,6 +177,26 @@ type RawAccess = {
     close: () => Promise<void>;
 };
 
+/** A namespace-scoped Engine grant. The caller must provide every grant explicitly. */
+type TokenGrant = Rivet.AuthTokenGrant;
+/** Options for `client.auth.issueToken()`. `expiresIn` is in seconds. */
+type IssueTokenOptions = Pick<Rivet.AuthTokenCreateRequest, "subject" | "grants"> & {
+    expiresIn?: Rivet.AuthTokenCreateRequest["duration"];
+};
+/** Token timestamps are Unix milliseconds. */
+interface IssuedToken {
+    token: Rivet.AuthTokenCreateResponse["token"];
+    issuedAt: Rivet.AuthTokenCreateResponse["issuedTs"];
+    expiresAt: Rivet.AuthTokenCreateResponse["expiresTs"];
+}
+/** Resources that can be scoped to a single actor ID. */
+type ActorTokenResource = Extract<Rivet.AuthTokenGrant["resource"], "actor_gateway" | "actor" | "actor_kv">;
+type ActorTokenPermissions = Partial<Record<ActorTokenResource, Rivet.AuthTokenGrant["operations"]>>;
+/** Options for `actor.issueToken()`. Omit permissions for gateway read access only. */
+type ActorIssueTokenOptions = Pick<IssueTokenOptions, "subject" | "expiresIn"> & {
+    permissions?: ActorTokenPermissions;
+};
+
 declare const EncodingSchema: z.ZodEnum<{
     json: "json";
     cbor: "cbor";
@@ -339,6 +360,29 @@ declare class UserError extends RivetError {
     constructor(message: string, options?: UserErrorOptions);
 }
 
+/** Sample rates keyed by action name, nested like the actor's action groups. */
+interface ActionSampleRates {
+    readonly [name: string]: number | ActionSampleRates;
+}
+/**
+ * {@link ActionSampleRates} limited to the actions of one actor, so a rate for
+ * an action that does not exist is a compile error.
+ */
+type ActionTraceSamplers<TActions> = {
+    readonly [K in keyof TActions]?: TActions[K] extends (...args: never[]) => unknown ? number : ActionTraceSamplers<TActions[K]>;
+};
+/** Trace sampling for one actor definition. */
+interface ActorTracingOptions<TActions> {
+    /**
+     * Share of this actor's invocations that are recorded, from 0 to 1. A rate
+     * lowers what is recorded and never raises it, so an invocation inside a
+     * trace the caller did not record is not recorded at any rate.
+     */
+    readonly sampler?: number;
+    /** Rates that replace `sampler` for single actions. */
+    readonly actions?: ActionTraceSamplers<TActions>;
+}
+
 type UpgradeWebSocket = (createEvents: (c: Context) => any) => Handler;
 type GetUpgradeWebSocket = () => UpgradeWebSocket;
 
@@ -349,6 +393,7 @@ interface GatewayRequestOptions {
     skipReadyWait?: boolean;
 }
 interface EngineControlClient {
+    issueToken(options: IssueTokenOptions): Promise<IssuedToken>;
     getForId(input: GetForIdInput): Promise<ActorOutput | undefined>;
     getWithKey(input: GetWithKeyInput): Promise<ActorOutput | undefined>;
     getOrCreateWithKey(input: GetOrCreateWithKeyInput): Promise<ActorOutput>;
@@ -356,6 +401,8 @@ interface EngineControlClient {
     listActors(input: ListActorsInput): Promise<ActorOutput[]>;
     sendRequest(target: GatewayTarget, actorRequest: Request, options?: GatewayRequestOptions): Promise<Response>;
     openWebSocket(path: string, target: GatewayTarget, encoding: Encoding, params: unknown, options?: GatewayRequestOptions): Promise<UniversalWebSocket>;
+    /** Refresh a credential rejected during this WebSocket handshake, if supported. */
+    refreshAuthToken?(ws: UniversalWebSocket): Promise<boolean>;
     proxyRequest(c: Context, actorRequest: Request, actorId: string): Promise<Response>;
     proxyWebSocket(c: Context, path: string, actorId: string, encoding: Encoding, params: unknown): Promise<Response>;
     buildGatewayUrl(target: GatewayTarget, options?: GatewayRequestOptions): Promise<string>;
@@ -638,12 +685,19 @@ interface RuntimeSqlBatchStatement {
 interface RuntimeSqlRunResult {
     changes: number;
 }
+/** Sample rates for the traces an actor starts, in the shape core takes. */
+interface RuntimeActorTracingConfig {
+    sampler?: number;
+    /** Keyed by flattened, dot-separated action name. */
+    actions?: Record<string, number>;
+}
 interface RuntimeActorConfig {
     name?: string;
     icon?: string;
     hasDatabase?: boolean;
     remoteSqlite?: boolean;
     sqliteProfiling?: SqliteProfilingOptions;
+    tracing?: RuntimeActorTracingConfig;
     enableActorRuntimeSocket?: boolean;
     hasState?: boolean;
     canHibernateWebsocket?: boolean;
@@ -1226,6 +1280,8 @@ declare class ActorHandleRaw {
      * Resolves the actor to get its unique actor ID.
      */
     resolve(): Promise<string>;
+    /** Issue a token scoped to this actor. Defaults to actor gateway read access. */
+    issueToken(options?: ActorIssueTokenOptions): Promise<IssuedToken>;
     /**
      * Returns the raw URL for routing traffic to the actor.
      */
@@ -1251,11 +1307,17 @@ declare class ActorHandleRaw {
 type ActorHandle<AD extends AnyActorDefinition> = Omit<ActorHandleRaw, "connect" | "send"> & {
     connect(params?: unknown, options?: ActorConnectOptions): ActorConn<AD>;
     resolve(): Promise<string>;
-} & ActorDefinitionQueueSend<AD> & ActorDefinitionActions<AD>;
+} & ActorDefinitionQueueSend<AD> & Omit<ActorDefinitionActions<AD>, keyof ActorHandleRaw>;
+
+/** Called when RivetKit needs a credential. Keep issuer secrets on your backend. */
+type GetToken = (options: {
+    forceRefresh: boolean;
+}) => Promise<string>;
 
 declare const ClientConfigSchema: z$1.ZodPipe<z$1.ZodObject<{
     endpoint: z$1.ZodPipe<z$1.ZodOptional<z$1.ZodString>, z$1.ZodTransform<string, string | undefined>>;
     token: z$1.ZodPipe<z$1.ZodOptional<z$1.ZodString>, z$1.ZodTransform<string | undefined, string | undefined>>;
+    getToken: z$1.ZodOptional<z$1.ZodCustom<GetToken, GetToken>>;
     namespace: z$1.ZodPipe<z$1.ZodOptional<z$1.ZodString>, z$1.ZodTransform<string | undefined, string | undefined>>;
     poolName: z$1.ZodDefault<z$1.ZodString>;
     encoding: z$1.ZodDefault<z$1.ZodEnum<{
@@ -1284,6 +1346,7 @@ declare const ClientConfigSchema: z$1.ZodPipe<z$1.ZodObject<{
     disableMetadataLookup: boolean;
     maxInputSize: number;
     devtools: boolean;
+    getToken?: GetToken | undefined;
     getUpgradeWebSocket?: GetUpgradeWebSocket | undefined;
 }, {
     endpoint: string;
@@ -1298,6 +1361,7 @@ declare const ClientConfigSchema: z$1.ZodPipe<z$1.ZodObject<{
     disableMetadataLookup: boolean;
     maxInputSize: number;
     devtools: boolean;
+    getToken?: GetToken | undefined;
     getUpgradeWebSocket?: GetUpgradeWebSocket | undefined;
 }>>;
 type ClientConfigInput = z$1.input<typeof ClientConfigSchema>;
@@ -1462,6 +1526,10 @@ interface ActorClientRuntimeOptions {
  */
 declare class ClientRaw {
     #private;
+    /** Issue namespace-scoped tokens with an explicit grant list. */
+    readonly auth: {
+        issueToken(options: IssueTokenOptions): Promise<IssuedToken>;
+    };
     [ACTOR_CONNS_SYMBOL]: Set<ActorConnRaw>;
     /**
      * Creates an instance of Client.
@@ -1522,9 +1590,9 @@ declare class ClientRaw {
  *
  * @template A The actor registry type.
  */
-type Client<A extends Registry<any>> = ClientRaw & {
+type Client<A extends Registry<any>> = ClientRaw & Omit<{
     [K in keyof ExtractActorsFromRegistry<A>]: ActorAccessor<ExtractActorsFromRegistry<A>[K]>;
-};
+}, keyof ClientRaw>;
 
 /** @experimental State exposed by a durable workflow run handler to the Inspector. */
 type WorkflowState = "pending" | "running" | "sleeping" | "failed" | "completed" | "cancelled" | "rolling_back";
@@ -1874,6 +1942,10 @@ declare const ActorConfigSchema: z.ZodObject<{
     onWebSocket: z.ZodOptional<z.ZodCustom<(...args: unknown[]) => unknown, (...args: unknown[]) => unknown>>;
     actions: z.ZodDefault<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
     actionInputSchemas: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    tracing: z.ZodOptional<z.ZodObject<{
+        sampler: z.ZodOptional<z.ZodNumber>;
+        actions: z.ZodOptional<z.ZodType<ActionSampleRates, unknown, z.core.$ZodTypeInternals<ActionSampleRates, unknown>>>;
+    }, z.core.$strict>>;
     connParamsSchema: z.ZodOptional<z.ZodAny>;
     events: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     queues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
@@ -2114,6 +2186,11 @@ interface BaseActorConfig<TState, TConnParams, TConnState, TVars, TInput, TDatab
      * May mirror nested action groups or use dot-separated low-level action names.
      */
     actionInputSchemas?: ActionInputSchemas;
+    /**
+     * How much of this actor's work is recorded in traces. Defaults to the
+     * process sampler from `OTEL_TRACES_SAMPLER`.
+     */
+    tracing?: ActorTracingOptions<TActions>;
     /**
      * Optional schema for validating connection params in native runtimes.
      */
@@ -2245,7 +2322,7 @@ declare const RegistryConfigSchema: z$2.ZodPipe<z$2.ZodObject<{
     endpoint: string | undefined;
     startServices: boolean;
     namespace: string;
-    token: string;
+    token: string | undefined;
     publicEndpoint: string | undefined;
     publicNamespace: string | undefined;
     publicToken: string | undefined;
@@ -2502,4 +2579,4 @@ declare class Registry<A extends RegistryActors> {
  */
 declare function createClient<A extends Registry<any>>(endpointOrConfig?: string | ClientConfigInput): Client<A>;
 
-export { type ActorAccessor, type ActorActionFunction, type ActorActionOptions, ActorClientError, type ActorConn, ActorConnDisposed, ActorConnRaw, type ActorConnStatus, type ActorConnectOptions, ActorDefinition, RivetError as ActorError, type ActorGatewayOptions, type ActorHandle, ActorHandleRaw, type AnyActorDefinition, type Client, type ClientConfigInput, ClientRaw, type ConnectionStateCallback, type CreateOptions, type CreateRequest, type Encoding, type EventUnsubscribe, type ExtractActorsFromRegistry, type ExtractRegistryFromClient, type GetOptions, type GetWithIdOptions, MalformedResponseMessage, ManagerError, type QueryOptions, type Region, RivetError, type StatusChangeCallback, UserError, createClient };
+export { type ActorAccessor, type ActorActionFunction, type ActorActionOptions, ActorClientError, type ActorConn, ActorConnDisposed, ActorConnRaw, type ActorConnStatus, type ActorConnectOptions, ActorDefinition, RivetError as ActorError, type ActorGatewayOptions, type ActorHandle, ActorHandleRaw, type ActorIssueTokenOptions, type ActorTokenPermissions, type ActorTokenResource, type AnyActorDefinition, type Client, type ClientConfigInput, ClientRaw, type ConnectionStateCallback, type CreateOptions, type CreateRequest, type Encoding, type EventUnsubscribe, type ExtractActorsFromRegistry, type ExtractRegistryFromClient, type GetOptions, type GetToken, type GetWithIdOptions, type IssueTokenOptions, type IssuedToken, MalformedResponseMessage, ManagerError, type QueryOptions, type Region, RivetError, type StatusChangeCallback, type TokenGrant, UserError, createClient };