@gigadrive/sdk 0.4.0 → 0.5.0

package/README.md

@@ -69,6 +69,29 @@ variables (constructor values take precedence):
 const client = new GigadriveClient({ bearerToken: 'eyJ...', fetch: myFetch });
 ```
 
+## Sticky sessions
+
+Deployed MicroVM functions can mint a routing URL that keeps the same opaque
+application key on one function instance. Workload credentials are injected by
+the platform, so no SDK configuration is required inside a deployment:
+
+```ts
+import { GigadriveClient } from '@gigadrive/sdk';
+
+const gigadrive = new GigadriveClient();
+const { url, expiresAt } = await gigadrive.stickySessions.createUrl({
+  key: gameId,
+  endpoint: '/socket',
+  expiresInSeconds: 14_400,
+});
+
+const socket = new WebSocket(url);
+```
+
+The URL is routing authority, not user authentication. Applications still own
+authorization and room membership. State remains in one MicroVM's memory, URLs
+expire, and deploys do not migrate that in-memory state to a new version.
+
 ## File uploads
 
 The high-level `upload()` computes the required SHA-256 checksum, infers the

package/dist/index.d.mts

@@ -2615,6 +2615,40 @@ declare class DeploymentsResource extends BaseResource {
     getHostnames(deploymentId: string): Promise<Paginated<Hostname>>;
 }
 
+/** Input for minting a routing-only sticky session URL. */
+interface CreateStickySessionUrlInput {
+    /** Opaque application key shared by callers that must reach the same instance. */
+    key: string;
+    /** Relative deployment route, including any application query parameters. */
+    endpoint: string;
+    /** HTTP method used to resolve the target route. Defaults to `GET`. */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'PATCH';
+    /** URL lifetime in seconds. Defaults to four hours; accepted range is 60–86,400. */
+    expiresInSeconds?: number;
+}
+/** A signed sticky URL and its absolute ISO 8601 expiration time. */
+interface CreateStickySessionUrlResult {
+    url: string;
+    expiresAt: string;
+}
+/**
+ * Creates protocol-independent sticky routing URLs for MicroVM functions.
+ *
+ * The URL selects an instance but does not authenticate an application user or
+ * store application state. Reusing the same key and unexpired URL keeps HTTP,
+ * streaming, and WebSocket traffic on the same function instance.
+ */
+declare class StickySessionsResource extends BaseResource {
+    /**
+     * Mints a signed URL for an opaque application key.
+     *
+     * Deployed Gigadrive workloads can call this with a zero-config
+     * `GigadriveClient`; the platform injects `GIGADRIVE_CLIENT_ID` and
+     * `GIGADRIVE_CLIENT_SECRET` using the SDK's existing credential chain.
+     */
+    createUrl(input: CreateStickySessionUrlInput): Promise<CreateStickySessionUrlResult>;
+}
+
 /**
  * Configuration for the {@link GigadriveClient}.
  *
@@ -2765,6 +2799,8 @@ declare class GigadriveClient {
     readonly aiGateway: AiGatewayResource;
     /** Application-scoped API key management (create, list, revoke). */
     readonly apiKeys: ApiKeysResource;
+    /** Signed URLs that keep related requests on one MicroVM instance. */
+    readonly stickySessions: StickySessionsResource;
     constructor(config?: GigadriveClientConfig);
 }
 
@@ -2903,4 +2939,4 @@ declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<
  */
 declare function parseSSEStream<T = unknown>(response: Response): AsyncGenerator<T>;
 
-export { AiGatewayAudioResource, type AiGatewayBudget, type AiGatewayBudgetInput, AiGatewayBudgetsResource, AiGatewayPoliciesResource, type AiGatewayPolicy, type AiGatewayPolicyInput, type AiGatewayProviderAttempt, type AiGatewayRequestEvent, type AiGatewayRequestsQuery, AiGatewayResource, type AiGatewayUsageBreakdown, type AiGatewayUsageQuery, AiGatewayUsageResource, type AiGatewayUsageSummary, AiGatewayVideosResource, type AiModel, type AiModelCapabilities, type AiModelRoutingProvider, ApiError, type ApiKey, ApiKeysResource, type Application, ApplicationEnvVarsResource, type ApplicationHostnameList, ApplicationRequestsResource, ApplicationStorageResource, ApplicationsResource, AuthenticationError, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionContentPart, type ChatCompletionMessage, type ChatCompletionRequest, type ChatCompletionResponse, type ChatCompletionUsage, type CreateApiKeyInput, type CreateApiKeyResult, type CreateDeploymentInput, type CreateEnvVarInput, type CreateOrganizationInput, type CreateStorageBucketInput, type CreateUploadSessionInput, type CreateUploadSessionResponse, type Deployment, type DeploymentLog, type DeploymentLogPage, type DeploymentLogType, type DeploymentStatus, DeploymentsResource, type EnvVar, type GatewayRequestOptions, type GatewayResult, GigadriveClient, type GigadriveClientConfig, GigadriveError, type Hostname, type HostnameAvailability, type ListApiKeysQuery, type ListApplicationsQuery, type ListDeploymentLogsQuery, type ListDeploymentsQuery, type ListQuery, type ListRequestsQuery, type ListStorageObjectsQuery, type NetworkRequest, type NetworkRequestApplicationRef, type NetworkRequestAssetRef, type NetworkRequestBucketRef, type NetworkRequestDeploymentRef, type NetworkRequestDetails, type NetworkRequestFunctionRef, type NetworkRequestMetrics, type NetworkRequestObjectRef, type NetworkRequestSummary, type NetworkResponseDetails, type NodeReadableLike, type Organization, OrganizationAiGatewayResource, OrganizationEnvVarsResource, type OrganizationMember, OrganizationMembersResource, type OrganizationMembershipRole, type OrganizationProductAccess, type OrganizationProductEntitlement, type OrganizationProductEntitlementCheck, type OrganizationProductSubscription, OrganizationProductsResource, OrganizationsResource, type Paginated, type PresignedUrlResult, type ProductAccessMode, type ProductAccessResolutionSource, type ProductDefaultAccessPolicy, type ProductDefinition, type ProductEntitlementStatus, type ProductPlan, type ProductSubscriptionStatus, type ProviderRouting, type PullEnvVarsQuery, type PullEnvVarsResult, type QueryValue, type ResolvedEnvVar, type ResponsesRequest, type ResponsesResponse, type RunUploadOptions, type SetProductionHostnameResult, type SpeechRequest, type StartUploadResult, type StorageBucket, StorageBucketsResource, type StorageObject, type StorageObjectAccess, type StorageObjectList, StorageObjectsResource, type StorageUploadSession, StorageUploadSessionsResource, type TranscriptionRequest, type TranscriptionResponse, type UpdateEnvVarInput, type UploadBatchItemResult, type UploadBatchOptions, type UploadByteSource, type UploadData, UploadError, type UploadFileInput, type UploadFileResult, type UploadPart, UploadSessionExpiredError, type UploadUrlStorage, type VideoGenerationRequest, type VideoGenerationResponse, type VideoModelList, type WaitForCompletionOptions, paginate, parseSSEStream };
+export { AiGatewayAudioResource, type AiGatewayBudget, type AiGatewayBudgetInput, AiGatewayBudgetsResource, AiGatewayPoliciesResource, type AiGatewayPolicy, type AiGatewayPolicyInput, type AiGatewayProviderAttempt, type AiGatewayRequestEvent, type AiGatewayRequestsQuery, AiGatewayResource, type AiGatewayUsageBreakdown, type AiGatewayUsageQuery, AiGatewayUsageResource, type AiGatewayUsageSummary, AiGatewayVideosResource, type AiModel, type AiModelCapabilities, type AiModelRoutingProvider, ApiError, type ApiKey, ApiKeysResource, type Application, ApplicationEnvVarsResource, type ApplicationHostnameList, ApplicationRequestsResource, ApplicationStorageResource, ApplicationsResource, AuthenticationError, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionContentPart, type ChatCompletionMessage, type ChatCompletionRequest, type ChatCompletionResponse, type ChatCompletionUsage, type CreateApiKeyInput, type CreateApiKeyResult, type CreateDeploymentInput, type CreateEnvVarInput, type CreateOrganizationInput, type CreateStickySessionUrlInput, type CreateStickySessionUrlResult, type CreateStorageBucketInput, type CreateUploadSessionInput, type CreateUploadSessionResponse, type Deployment, type DeploymentLog, type DeploymentLogPage, type DeploymentLogType, type DeploymentStatus, DeploymentsResource, type EnvVar, type GatewayRequestOptions, type GatewayResult, GigadriveClient, type GigadriveClientConfig, GigadriveError, type Hostname, type HostnameAvailability, type ListApiKeysQuery, type ListApplicationsQuery, type ListDeploymentLogsQuery, type ListDeploymentsQuery, type ListQuery, type ListRequestsQuery, type ListStorageObjectsQuery, type NetworkRequest, type NetworkRequestApplicationRef, type NetworkRequestAssetRef, type NetworkRequestBucketRef, type NetworkRequestDeploymentRef, type NetworkRequestDetails, type NetworkRequestFunctionRef, type NetworkRequestMetrics, type NetworkRequestObjectRef, type NetworkRequestSummary, type NetworkResponseDetails, type NodeReadableLike, type Organization, OrganizationAiGatewayResource, OrganizationEnvVarsResource, type OrganizationMember, OrganizationMembersResource, type OrganizationMembershipRole, type OrganizationProductAccess, type OrganizationProductEntitlement, type OrganizationProductEntitlementCheck, type OrganizationProductSubscription, OrganizationProductsResource, OrganizationsResource, type Paginated, type PresignedUrlResult, type ProductAccessMode, type ProductAccessResolutionSource, type ProductDefaultAccessPolicy, type ProductDefinition, type ProductEntitlementStatus, type ProductPlan, type ProductSubscriptionStatus, type ProviderRouting, type PullEnvVarsQuery, type PullEnvVarsResult, type QueryValue, type ResolvedEnvVar, type ResponsesRequest, type ResponsesResponse, type RunUploadOptions, type SetProductionHostnameResult, type SpeechRequest, type StartUploadResult, StickySessionsResource, type StorageBucket, StorageBucketsResource, type StorageObject, type StorageObjectAccess, type StorageObjectList, StorageObjectsResource, type StorageUploadSession, StorageUploadSessionsResource, type TranscriptionRequest, type TranscriptionResponse, type UpdateEnvVarInput, type UploadBatchItemResult, type UploadBatchOptions, type UploadByteSource, type UploadData, UploadError, type UploadFileInput, type UploadFileResult, type UploadPart, UploadSessionExpiredError, type UploadUrlStorage, type VideoGenerationRequest, type VideoGenerationResponse, type VideoModelList, type WaitForCompletionOptions, paginate, parseSSEStream };

package/dist/index.d.ts

@@ -2615,6 +2615,40 @@ declare class DeploymentsResource extends BaseResource {
     getHostnames(deploymentId: string): Promise<Paginated<Hostname>>;
 }
 
+/** Input for minting a routing-only sticky session URL. */
+interface CreateStickySessionUrlInput {
+    /** Opaque application key shared by callers that must reach the same instance. */
+    key: string;
+    /** Relative deployment route, including any application query parameters. */
+    endpoint: string;
+    /** HTTP method used to resolve the target route. Defaults to `GET`. */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'PATCH';
+    /** URL lifetime in seconds. Defaults to four hours; accepted range is 60–86,400. */
+    expiresInSeconds?: number;
+}
+/** A signed sticky URL and its absolute ISO 8601 expiration time. */
+interface CreateStickySessionUrlResult {
+    url: string;
+    expiresAt: string;
+}
+/**
+ * Creates protocol-independent sticky routing URLs for MicroVM functions.
+ *
+ * The URL selects an instance but does not authenticate an application user or
+ * store application state. Reusing the same key and unexpired URL keeps HTTP,
+ * streaming, and WebSocket traffic on the same function instance.
+ */
+declare class StickySessionsResource extends BaseResource {
+    /**
+     * Mints a signed URL for an opaque application key.
+     *
+     * Deployed Gigadrive workloads can call this with a zero-config
+     * `GigadriveClient`; the platform injects `GIGADRIVE_CLIENT_ID` and
+     * `GIGADRIVE_CLIENT_SECRET` using the SDK's existing credential chain.
+     */
+    createUrl(input: CreateStickySessionUrlInput): Promise<CreateStickySessionUrlResult>;
+}
+
 /**
  * Configuration for the {@link GigadriveClient}.
  *
@@ -2765,6 +2799,8 @@ declare class GigadriveClient {
     readonly aiGateway: AiGatewayResource;
     /** Application-scoped API key management (create, list, revoke). */
     readonly apiKeys: ApiKeysResource;
+    /** Signed URLs that keep related requests on one MicroVM instance. */
+    readonly stickySessions: StickySessionsResource;
     constructor(config?: GigadriveClientConfig);
 }
 
@@ -2903,4 +2939,4 @@ declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<
  */
 declare function parseSSEStream<T = unknown>(response: Response): AsyncGenerator<T>;
 
-export { AiGatewayAudioResource, type AiGatewayBudget, type AiGatewayBudgetInput, AiGatewayBudgetsResource, AiGatewayPoliciesResource, type AiGatewayPolicy, type AiGatewayPolicyInput, type AiGatewayProviderAttempt, type AiGatewayRequestEvent, type AiGatewayRequestsQuery, AiGatewayResource, type AiGatewayUsageBreakdown, type AiGatewayUsageQuery, AiGatewayUsageResource, type AiGatewayUsageSummary, AiGatewayVideosResource, type AiModel, type AiModelCapabilities, type AiModelRoutingProvider, ApiError, type ApiKey, ApiKeysResource, type Application, ApplicationEnvVarsResource, type ApplicationHostnameList, ApplicationRequestsResource, ApplicationStorageResource, ApplicationsResource, AuthenticationError, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionContentPart, type ChatCompletionMessage, type ChatCompletionRequest, type ChatCompletionResponse, type ChatCompletionUsage, type CreateApiKeyInput, type CreateApiKeyResult, type CreateDeploymentInput, type CreateEnvVarInput, type CreateOrganizationInput, type CreateStorageBucketInput, type CreateUploadSessionInput, type CreateUploadSessionResponse, type Deployment, type DeploymentLog, type DeploymentLogPage, type DeploymentLogType, type DeploymentStatus, DeploymentsResource, type EnvVar, type GatewayRequestOptions, type GatewayResult, GigadriveClient, type GigadriveClientConfig, GigadriveError, type Hostname, type HostnameAvailability, type ListApiKeysQuery, type ListApplicationsQuery, type ListDeploymentLogsQuery, type ListDeploymentsQuery, type ListQuery, type ListRequestsQuery, type ListStorageObjectsQuery, type NetworkRequest, type NetworkRequestApplicationRef, type NetworkRequestAssetRef, type NetworkRequestBucketRef, type NetworkRequestDeploymentRef, type NetworkRequestDetails, type NetworkRequestFunctionRef, type NetworkRequestMetrics, type NetworkRequestObjectRef, type NetworkRequestSummary, type NetworkResponseDetails, type NodeReadableLike, type Organization, OrganizationAiGatewayResource, OrganizationEnvVarsResource, type OrganizationMember, OrganizationMembersResource, type OrganizationMembershipRole, type OrganizationProductAccess, type OrganizationProductEntitlement, type OrganizationProductEntitlementCheck, type OrganizationProductSubscription, OrganizationProductsResource, OrganizationsResource, type Paginated, type PresignedUrlResult, type ProductAccessMode, type ProductAccessResolutionSource, type ProductDefaultAccessPolicy, type ProductDefinition, type ProductEntitlementStatus, type ProductPlan, type ProductSubscriptionStatus, type ProviderRouting, type PullEnvVarsQuery, type PullEnvVarsResult, type QueryValue, type ResolvedEnvVar, type ResponsesRequest, type ResponsesResponse, type RunUploadOptions, type SetProductionHostnameResult, type SpeechRequest, type StartUploadResult, type StorageBucket, StorageBucketsResource, type StorageObject, type StorageObjectAccess, type StorageObjectList, StorageObjectsResource, type StorageUploadSession, StorageUploadSessionsResource, type TranscriptionRequest, type TranscriptionResponse, type UpdateEnvVarInput, type UploadBatchItemResult, type UploadBatchOptions, type UploadByteSource, type UploadData, UploadError, type UploadFileInput, type UploadFileResult, type UploadPart, UploadSessionExpiredError, type UploadUrlStorage, type VideoGenerationRequest, type VideoGenerationResponse, type VideoModelList, type WaitForCompletionOptions, paginate, parseSSEStream };
+export { AiGatewayAudioResource, type AiGatewayBudget, type AiGatewayBudgetInput, AiGatewayBudgetsResource, AiGatewayPoliciesResource, type AiGatewayPolicy, type AiGatewayPolicyInput, type AiGatewayProviderAttempt, type AiGatewayRequestEvent, type AiGatewayRequestsQuery, AiGatewayResource, type AiGatewayUsageBreakdown, type AiGatewayUsageQuery, AiGatewayUsageResource, type AiGatewayUsageSummary, AiGatewayVideosResource, type AiModel, type AiModelCapabilities, type AiModelRoutingProvider, ApiError, type ApiKey, ApiKeysResource, type Application, ApplicationEnvVarsResource, type ApplicationHostnameList, ApplicationRequestsResource, ApplicationStorageResource, ApplicationsResource, AuthenticationError, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionContentPart, type ChatCompletionMessage, type ChatCompletionRequest, type ChatCompletionResponse, type ChatCompletionUsage, type CreateApiKeyInput, type CreateApiKeyResult, type CreateDeploymentInput, type CreateEnvVarInput, type CreateOrganizationInput, type CreateStickySessionUrlInput, type CreateStickySessionUrlResult, type CreateStorageBucketInput, type CreateUploadSessionInput, type CreateUploadSessionResponse, type Deployment, type DeploymentLog, type DeploymentLogPage, type DeploymentLogType, type DeploymentStatus, DeploymentsResource, type EnvVar, type GatewayRequestOptions, type GatewayResult, GigadriveClient, type GigadriveClientConfig, GigadriveError, type Hostname, type HostnameAvailability, type ListApiKeysQuery, type ListApplicationsQuery, type ListDeploymentLogsQuery, type ListDeploymentsQuery, type ListQuery, type ListRequestsQuery, type ListStorageObjectsQuery, type NetworkRequest, type NetworkRequestApplicationRef, type NetworkRequestAssetRef, type NetworkRequestBucketRef, type NetworkRequestDeploymentRef, type NetworkRequestDetails, type NetworkRequestFunctionRef, type NetworkRequestMetrics, type NetworkRequestObjectRef, type NetworkRequestSummary, type NetworkResponseDetails, type NodeReadableLike, type Organization, OrganizationAiGatewayResource, OrganizationEnvVarsResource, type OrganizationMember, OrganizationMembersResource, type OrganizationMembershipRole, type OrganizationProductAccess, type OrganizationProductEntitlement, type OrganizationProductEntitlementCheck, type OrganizationProductSubscription, OrganizationProductsResource, OrganizationsResource, type Paginated, type PresignedUrlResult, type ProductAccessMode, type ProductAccessResolutionSource, type ProductDefaultAccessPolicy, type ProductDefinition, type ProductEntitlementStatus, type ProductPlan, type ProductSubscriptionStatus, type ProviderRouting, type PullEnvVarsQuery, type PullEnvVarsResult, type QueryValue, type ResolvedEnvVar, type ResponsesRequest, type ResponsesResponse, type RunUploadOptions, type SetProductionHostnameResult, type SpeechRequest, type StartUploadResult, StickySessionsResource, type StorageBucket, StorageBucketsResource, type StorageObject, type StorageObjectAccess, type StorageObjectList, StorageObjectsResource, type StorageUploadSession, StorageUploadSessionsResource, type TranscriptionRequest, type TranscriptionResponse, type UpdateEnvVarInput, type UploadBatchItemResult, type UploadBatchOptions, type UploadByteSource, type UploadData, UploadError, type UploadFileInput, type UploadFileResult, type UploadPart, UploadSessionExpiredError, type UploadUrlStorage, type VideoGenerationRequest, type VideoGenerationResponse, type VideoModelList, type WaitForCompletionOptions, paginate, parseSSEStream };

package/dist/index.js

@@ -51,6 +51,7 @@ __export(src_exports, {
   OrganizationMembersResource: () => OrganizationMembersResource,
   OrganizationProductsResource: () => OrganizationProductsResource,
   OrganizationsResource: () => OrganizationsResource,
+  StickySessionsResource: () => StickySessionsResource,
   StorageBucketsResource: () => StorageBucketsResource,
   StorageObjectsResource: () => StorageObjectsResource,
   StorageUploadSessionsResource: () => StorageUploadSessionsResource,
@@ -2275,6 +2276,23 @@ var OrganizationsResource = class extends BaseResource {
   }
 };
 
+// src/resources/sticky-sessions.ts
+var StickySessionsResource = class extends BaseResource {
+  /**
+   * Mints a signed URL for an opaque application key.
+   *
+   * Deployed Gigadrive workloads can call this with a zero-config
+   * `GigadriveClient`; the platform injects `GIGADRIVE_CLIENT_ID` and
+   * `GIGADRIVE_CLIENT_SECRET` using the SDK's existing credential chain.
+   */
+  async createUrl(input) {
+    return this.httpClient.post("/sticky-sessions/urls", {
+      ...input,
+      method: input.method ?? "GET"
+    });
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL2 = "https://api.gigadrive.network";
 var GigadriveClient = class {
@@ -2288,6 +2306,8 @@ var GigadriveClient = class {
   aiGateway;
   /** Application-scoped API key management (create, list, revoke). */
   apiKeys;
+  /** Signed URLs that keep related requests on one MicroVM instance. */
+  stickySessions;
   constructor(config = {}) {
     const baseUrl = config.baseUrl ?? readEnv("GIGADRIVE_API_BASE_URL") ?? DEFAULT_BASE_URL2;
     const fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
@@ -2299,6 +2319,7 @@ var GigadriveClient = class {
     this.deployments = new DeploymentsResource(httpClient);
     this.aiGateway = new AiGatewayResource(httpClient);
     this.apiKeys = new ApiKeysResource(httpClient);
+    this.stickySessions = new StickySessionsResource(httpClient);
   }
 };
 
@@ -2336,6 +2357,7 @@ async function* paginate(fetchPage) {
   OrganizationMembersResource,
   OrganizationProductsResource,
   OrganizationsResource,
+  StickySessionsResource,
   StorageBucketsResource,
   StorageObjectsResource,
   StorageUploadSessionsResource,