@gigadrive/sdk 0.3.0 → 0.5.0

package/README.md

@@ -29,6 +29,28 @@ const { items: organizations } = await client.organizations.list();
 const { items: applications } = await client.applications.list();
 ```
 
+## Organizations and product entitlements
+
+Organizations are the top-level account containers for Gigadrive products.
+Beyond listing orgs, the SDK can create organizations, inspect members, and
+check product entitlements (read-only; the SDK does not activate or change plans):
+
+```ts
+// Create an organization (user-backed token + platform:organizations:write)
+const org = await client.organizations.create({ name: 'Acme Corp' });
+
+// Fetch one organization and its members
+const details = await client.organizations.get(org.id);
+const { items: members } = await client.organizations.members.list(org.id);
+
+// Inspect product access / entitlements (read-only)
+const { items: products } = await client.organizations.products.list(org.id);
+const office = await client.organizations.products.get(org.id, 'office');
+const check = await client.organizations.products.checkEntitlement(org.id, 'office');
+
+console.log(details.name, members.length, office.hasAccess, check.hasAccess, products.length);
+```
+
 ## Authentication
 
 Authentication is handled for you — tokens are fetched, cached, and refreshed
@@ -47,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

@@ -1865,6 +1865,204 @@ declare class OrganizationEnvVarsResource extends BaseResource {
     delete(organizationId: string, envVarId: string): Promise<void>;
 }
 
+/** Organization membership role used for administration privileges. */
+type OrganizationMembershipRole = 'OWNER' | 'ADMIN' | 'MEMBER';
+/** A user membership in a Gigadrive organization. */
+interface OrganizationMember {
+    /** Unique membership identifier (UUID). */
+    membershipId: string;
+    /** Organization that owns this membership. */
+    organizationId: string;
+    /** User who belongs to the organization. */
+    userId: string;
+    /** Email address of the organization member. */
+    email: string;
+    /** Given name of the organization member, or null when unset. */
+    givenName: string | null;
+    /** Family name of the organization member, or null when unset. */
+    familyName: string | null;
+    /** Avatar URL for the organization member, or null when unset. */
+    imageUrl: string | null;
+    /** Organization membership role. */
+    role: OrganizationMembershipRole;
+    /** ISO 8601 timestamp when the user joined the organization. */
+    joinedAt: string;
+}
+/**
+ * List organization members. Accessed via {@link OrganizationsResource.members}.
+ *
+ * @example
+ * ```ts
+ * const { items } = await client.organizations.members.list('org-id');
+ * console.log(items.map((m) => `${m.email} (${m.role})`));
+ * ```
+ */
+declare class OrganizationMembersResource extends BaseResource {
+    /**
+     * List the users who belong to an organization.
+     *
+     * @param organizationId - Organization whose members should be listed.
+     * @param query - Optional pagination.
+     * @returns A paginated list of organization members.
+     *
+     * @example
+     * ```ts
+     * const { items, total } = await client.organizations.members.list('org-id');
+     * console.log(`Found ${total} members`);
+     * ```
+     */
+    list(organizationId: string, query?: ListQuery): Promise<Paginated<OrganizationMember>>;
+}
+
+/** Product access mode from the code-defined product registry. */
+type ProductAccessMode = 'organization' | 'user';
+/** Fallback access policy when no explicit entitlement override exists. */
+type ProductDefaultAccessPolicy = 'granted' | 'explicit_entitlement_required';
+/** Lifecycle status of an explicit product entitlement override. */
+type ProductEntitlementStatus = 'ACTIVE' | 'SUSPENDED' | 'REVOKED';
+/** Lifecycle status of a local organization product subscription. */
+type ProductSubscriptionStatus = 'ACTIVE' | 'CANCELED';
+/** Whether effective access was resolved from an override or the registry default. */
+type ProductAccessResolutionSource = 'explicit' | 'default';
+/** A plan defined for a product in the product registry. */
+interface ProductPlan {
+    /** Stable plan slug. */
+    slug: string;
+    /** Human-readable plan name. */
+    displayName: string;
+    /** Short description of the plan. */
+    description: string;
+}
+/** Product metadata from the code-defined product registry. */
+interface ProductDefinition {
+    /** Stable product slug (e.g. `network`, `office`). */
+    slug: string;
+    /** Human-readable product name. */
+    displayName: string;
+    /** Whether the product is granted to organizations or directly to users. */
+    accessMode: ProductAccessMode;
+    /** Fallback access policy when no explicit entitlement override exists. */
+    defaultAccessPolicy: ProductDefaultAccessPolicy;
+    /** Locally activatable plans for the product. */
+    plans: ProductPlan[];
+}
+/** Explicit organization product entitlement override. */
+interface OrganizationProductEntitlement {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** Product slug this entitlement applies to. */
+    product: string;
+    /** Lifecycle status of the override. */
+    status: ProductEntitlementStatus;
+    /** User who last granted or updated the override, if known. */
+    grantedByUserId: string | null;
+    /** ISO 8601 timestamp when the entitlement was revoked, if revoked. */
+    revokedAt: string | null;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+}
+/** Local organization product subscription / plan selection. */
+interface OrganizationProductSubscription {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** Product slug this subscription applies to. */
+    product: string;
+    /** Currently selected plan slug. */
+    plan: string;
+    /** Local subscription lifecycle status. */
+    status: ProductSubscriptionStatus;
+    /** User who activated the current plan, if known. */
+    activatedByUserId: string | null;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+}
+/** Effective product access summary for an organization-scoped product. */
+interface OrganizationProductAccess {
+    /** Product metadata from the registry. */
+    product: ProductDefinition;
+    /** Whether the organization currently has effective access. */
+    hasAccess: boolean;
+    /** Whether access was resolved from an explicit override or the default policy. */
+    resolutionSource: ProductAccessResolutionSource;
+    /** Explicit entitlement override when one exists. */
+    explicitEntitlement: OrganizationProductEntitlement | null;
+    /** Local product subscription when one exists. */
+    subscription: OrganizationProductSubscription | null;
+}
+/** Compact yes/no entitlement check for an organization product. */
+interface OrganizationProductEntitlementCheck {
+    /** Organization that was checked. */
+    organizationId: string;
+    /** Product slug that was checked. */
+    product: string;
+    /** Whether the organization currently has effective access. */
+    hasAccess: boolean;
+}
+/**
+ * Inspect organization product access / entitlements.
+ *
+ * Accessed via {@link OrganizationsResource.products}.
+ *
+ * Subscriptions are read-only through the public API — plan changes happen in
+ * Gigadrive product surfaces, not via the SDK.
+ *
+ * @example
+ * ```ts
+ * const { items } = await client.organizations.products.list('org-id');
+ * const check = await client.organizations.products.checkEntitlement('org-id', 'office');
+ * console.log(check.hasAccess);
+ * ```
+ */
+declare class OrganizationProductsResource extends BaseResource {
+    /**
+     * List effective product access for every organization-scoped product.
+     *
+     * @param organizationId - Organization whose product access should be listed.
+     * @param query - Optional pagination.
+     * @returns A paginated list of product access summaries.
+     *
+     * @example
+     * ```ts
+     * const { items } = await client.organizations.products.list('org-id');
+     * for (const item of items) {
+     *   console.log(item.product.slug, item.hasAccess);
+     * }
+     * ```
+     */
+    list(organizationId: string, query?: ListQuery): Promise<Paginated<OrganizationProductAccess>>;
+    /**
+     * Get effective access for one organization-scoped product.
+     *
+     * @param organizationId - Organization to inspect.
+     * @param product - Product slug from the product registry.
+     * @returns Product access summary including entitlement and subscription state.
+     *
+     * @example
+     * ```ts
+     * const access = await client.organizations.products.get('org-id', 'office');
+     * console.log(access.hasAccess, access.subscription?.plan);
+     * ```
+     */
+    get(organizationId: string, product: string): Promise<OrganizationProductAccess>;
+    /**
+     * Check whether an organization currently has access to a product.
+     *
+     * @param organizationId - Organization to check.
+     * @param product - Product slug from the product registry.
+     * @returns Compact entitlement check result.
+     *
+     * @example
+     * ```ts
+     * const { hasAccess } = await client.organizations.products.checkEntitlement('org-id', 'network');
+     * ```
+     */
+    checkEntitlement(organizationId: string, product: string): Promise<OrganizationProductEntitlementCheck>;
+}
+
 /** A Gigadrive Network organization. */
 interface Organization {
     /** Unique identifier (UUID). */
@@ -1880,6 +2078,13 @@ interface Organization {
     /** ISO 8601 last-updated timestamp. */
     updatedAt: string;
 }
+/** Input for creating an organization. */
+interface CreateOrganizationInput {
+    /** Display name for the new organization. */
+    name: string;
+    /** Optional URL-safe slug. Generated from the name when omitted. */
+    slug?: string;
+}
 /**
  * Manage organizations. Accessed via {@link GigadriveClient.organizations}.
  *
@@ -1918,6 +2123,25 @@ declare class OrganizationsResource extends BaseResource {
      * ```
      */
     readonly aiGateway: OrganizationAiGatewayResource;
+    /**
+     * List organization members and membership roles.
+     *
+     * @example
+     * ```ts
+     * const { items } = await client.organizations.members.list('org-id');
+     * ```
+     */
+    readonly members: OrganizationMembersResource;
+    /**
+     * Inspect organization product entitlements. Read-only through the public
+     * API — plan changes happen in Gigadrive product surfaces, not via the SDK.
+     *
+     * @example
+     * ```ts
+     * const check = await client.organizations.products.checkEntitlement('org-id', 'office');
+     * ```
+     */
+    readonly products: OrganizationProductsResource;
     constructor(...args: ConstructorParameters<typeof BaseResource>);
     /**
      * List organizations the authenticated actor has access to.
@@ -1932,6 +2156,35 @@ declare class OrganizationsResource extends BaseResource {
      * ```
      */
     list(query?: ListQuery): Promise<Paginated<Organization>>;
+    /**
+     * Get a single organization by ID.
+     *
+     * @param organizationId - Organization to retrieve.
+     * @returns The organization.
+     *
+     * @example
+     * ```ts
+     * const org = await client.organizations.get('org-id');
+     * console.log(org.name, org.slug);
+     * ```
+     */
+    get(organizationId: string): Promise<Organization>;
+    /**
+     * Create a new organization.
+     *
+     * Requires a user-backed token with the `platform:organizations:write` scope.
+     * The authenticated user becomes the organization owner.
+     *
+     * @param input - Organization creation input.
+     * @returns The created organization.
+     *
+     * @example
+     * ```ts
+     * const org = await client.organizations.create({ name: 'Acme Corp' });
+     * console.log(org.id, org.slug);
+     * ```
+     */
+    create(input: CreateOrganizationInput): Promise<Organization>;
 }
 
 /** A Gigadrive Network application, belonging to an {@link Organization}. */
@@ -2362,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}.
  *
@@ -2512,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);
 }
 
@@ -2650,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 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, OrganizationsResource, type Paginated, type PresignedUrlResult, 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 };