introduce DevelopmentTokenServer and deprecate SandboxTokenServer

.changeset/goofy-rules-swim.md

@@ -0,0 +1,5 @@
+---
+"livekit-client": minor
+---
+
+introduce DevelopmentTokenServer and deprecate SandboxTokenServer

README.md

@@ -336,7 +336,7 @@ room.connect(configurableResponse.serverUrl, configurableResponse.participantTok
 |Mechanism:   | using pre-generated credentials | via a http request to a url | via fully custom logic |
 |-------------|--|--|--|
 |Fixed        | [`TokenSource.literal`](#tokensourceliteral) | — | [`TokenSource.literal(async () => { /* ... */ })`](#tokensourceliteral) |
-|Configurable | — | [`TokenSource.endpoint`](#tokensourceendpoint) or [`TokenSource.sandboxTokenServer`](#tokensourceendpoint)  | [`TokenSource.custom`](#tokensourcecustom) |
+|Configurable | — | [`TokenSource.endpoint`](#tokensourceendpoint) or [`TokenSource.developmentTokenServer`](#tokensourcedevelopmenttokenserver)  | [`TokenSource.custom`](#tokensourcecustom) |
 
 #### TokenSource.Literal
 A fixed token source which returns a static set of credentials or a computed set of credentials
@@ -373,21 +373,22 @@ const endpoint2 = TokenSource.endpoint("http://example.com/credentials-endpoint"
 await endpoint2.fetch({ agentName: "agent to dispatch" }) // { serverUrl: "...", participantToken: "... token encoding agentName ..." }
 ```
 
-#### TokenSource.SandboxTokenServer
+#### TokenSource.DevelopmentTokenServer
 A configurable token source which makes a request to a
-[sandbox token server endpoint](https://cloud.livekit.io/projects/p_/sandbox/templates/token-server),
+// TODO fix the dashboard link
+[development token server endpoint](https://cloud.livekit.io/projects/p_/sandbox/templates/token-server),
 a LiveKit-hosted token generation mechanism.
 
 This token generation mechanism is inherently insecure and should only be used for
 prototyping; do NOT use in production.
 
-One parameter is required - the sandbox id from the dashboard. This is the `token-server-xxxxxx`
+One parameter is required - the development token server id from the dashboard. This is the `token-server-xxxxxx`
 value in `https://token-server-xxxxxx.sandbox.livekit.io`.
 
 Example:
 ```ts
-const sandbox = TokenSource.sandboxTokenServer("token-server-xxxxxx");
-await sandbox.fetch({ agentName: "agent to dispatch" }); // { serverUrl: "...", participantToken: "... token encoding agentName ..." }
+const devTokenSource = TokenSource.developmentTokenServer("token-server-xxxxxx");
+await devTokenSource.fetch({ agentName: "agent to dispatch" }); // { serverUrl: "...", participantToken: "... token encoding agentName ..." }
 ```
 
 #### TokenSource.Custom
@@ -401,11 +402,11 @@ output token. If you'd rather implement a fixed version of this TokenSource, see
 
 Example:
 ```ts
-const sandbox = TokenSource.custom(async (options) => {
+const myTokenSource = TokenSource.custom(async (options) => {
   // generate token info via custom means here
   return { serverUrl: "...", participantToken: "... options encoded in here ..." };
 });
-await sandbox.fetch({ agentName: "agent to dispatch" });
+await myTokenSource.fetch({ agentName: "agent to dispatch" });
 ```
 
 ### RPC

src/room/token-source/TokenSource.ts

@@ -213,38 +213,45 @@ class TokenSourceEndpoint extends TokenSourceCached {
     const body = await response.json();
     return TokenSourceResponse.fromJson(body, {
       // NOTE: it could be possible that the response body could contain more fields than just
-      // what's in TokenSourceResponse depending on the implementation (ie, SandboxTokenServer)
+      // what's in TokenSourceResponse depending on the implementation (ie, DevelopmentTokenServer)
       ignoreUnknownFields: true,
     });
   }
 }
 
-export type SandboxTokenServerOptions = {
+export type DevelopmentTokenServerOptions = {
   baseUrl?: string;
 };
-
-class TokenSourceSandboxTokenServer extends TokenSourceEndpoint {
-  constructor(sandboxId: string, options: SandboxTokenServerOptions) {
+class TokenSourceDevelopmentTokenServer extends TokenSourceEndpoint {
+  constructor(tokenServerId: string, options: DevelopmentTokenServerOptions) {
     const { baseUrl = 'https://cloud-api.livekit.io', ...rest } = options;
 
+    // TODO is there an alternative path (and header) already that we could use instead of the sandbox naming one?
     super(`${baseUrl}/api/v2/sandbox/connection-details`, {
       ...rest,
       headers: {
-        'X-Sandbox-ID': sandboxId,
+        'X-Sandbox-ID': tokenServerId,
       },
     });
   }
 }
 
+/** @deprecated use {@link DevelopmentTokenServerOptions} instead */
+export type SandboxTokenServerOptions = DevelopmentTokenServerOptions;
+
+/** @deprecated Use {@link TokenSourceDevelopmentTokenServer} instead */
+class TokenSourceSandboxTokenServer extends TokenSourceDevelopmentTokenServer {}
+
 export {
   /** The return type of {@link TokenSource.literal} */
   type TokenSourceLiteral,
   /** The return type of {@link TokenSource.custom} */
   type TokenSourceCustom,
   /** The return type of {@link TokenSource.endpoint} */
   type TokenSourceEndpoint,
-  /** The return type of {@link TokenSource.sandboxTokenServer} */
   type TokenSourceSandboxTokenServer,
+  /** The return type of {@link TokenSource.developmentTokenServer} */
+  type TokenSourceDevelopmentTokenServer,
   decodeTokenPayload,
   areTokenSourceFetchOptionsEqual,
 };
@@ -276,15 +283,22 @@ export const TokenSource = {
   },
 
   /**
-   * TokenSource.sandboxTokenServer queries a sandbox token server for credentials,
+   * @deprecated Use {@link TokenSource.developmentTokenServer} instead
+   */
+  sandboxTokenServer(sandboxId: string, options: SandboxTokenServerOptions = {}) {
+    return new TokenSourceSandboxTokenServer(sandboxId, options);
+  },
+
+  /**
+   * TokenSource.developmentTokenServer queries a development token server for credentials,
    * which supports quick prototyping / getting started types of use cases.
    *
    * This token provider is INSECURE and should NOT be used in production.
    *
    * For more info:
    * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server
    */
-  sandboxTokenServer(sandboxId: string, options: SandboxTokenServerOptions = {}) {
-    return new TokenSourceSandboxTokenServer(sandboxId, options);
+  developmentTokenServer(tokenServerId: string, options: DevelopmentTokenServerOptions = {}) {
+    return new TokenSourceDevelopmentTokenServer(tokenServerId, options);
   },
 };