@gigadrive/sdk 0.2.0 → 0.4.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

package/dist/index.d.mts

@@ -488,6 +488,83 @@ declare class AiGatewayResource extends BaseResource {
     getModel(modelId: string): Promise<AiModel>;
 }
 
+/** An application-scoped API key. The secret is never returned after creation. */
+interface ApiKey {
+    /** Unique identifier (UUID). Used as the OAuth client ID. */
+    id: string;
+    /** Human-readable label. */
+    name: string;
+    /** Application this key is scoped to. */
+    applicationId: string | null;
+    /** API capability scopes granted to the key. */
+    scopes: string[];
+    /** ISO 8601 expiry, or `null` if the key never expires. */
+    expiresAt: string | null;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+}
+/** Input for creating an application-scoped API key. */
+interface CreateApiKeyInput {
+    /** Human-readable label for the key. */
+    name: string;
+    /** Application to scope the key to. The key can only act on this application. */
+    applicationId: string;
+    /**
+     * API capability scopes to grant. Each must be a subset of your own access and
+     * cannot include API key management. Defaults to a minimal read-only set.
+     */
+    scopes?: string[];
+    /** Optional ISO 8601 expiry. Defaults to 90 days when omitted. */
+    expiresAt?: string;
+}
+/**
+ * The result of creating an API key. Includes the plaintext {@link secret},
+ * which is returned only once and cannot be retrieved again.
+ */
+interface CreateApiKeyResult extends ApiKey {
+    /** The plaintext client secret. Store it now — it cannot be retrieved again. */
+    secret: string;
+}
+/** Query for {@link ApiKeysResource.list}. */
+interface ListApiKeysQuery {
+    /** Application whose keys should be listed. */
+    applicationId: string;
+}
+/**
+ * Manage application-scoped API keys. Accessed via {@link GigadriveClient.apiKeys}.
+ *
+ * @example
+ * ```ts
+ * const key = await client.apiKeys.create({ name: 'ci', applicationId: 'app-id' });
+ * // Use key.id + key.secret as OAuth client credentials. Store the secret now.
+ * ```
+ */
+declare class ApiKeysResource extends BaseResource {
+    /**
+     * Provision a new application-scoped API key. The plaintext secret is returned
+     * exactly once — store it immediately.
+     *
+     * @param data - The key name, target application, and optional scopes/expiry.
+     * @returns The created key including its one-time plaintext secret.
+     */
+    create(data: CreateApiKeyInput): Promise<CreateApiKeyResult>;
+    /**
+     * List the API keys scoped to an application. Secrets are never returned.
+     *
+     * @param query - The application whose keys should be listed.
+     * @returns A paginated list of API key metadata.
+     */
+    list(query: ListApiKeysQuery): Promise<Paginated<ApiKey>>;
+    /**
+     * Permanently revoke an API key.
+     *
+     * @param apiKeyId - The API key ID (UUID).
+     */
+    delete(apiKeyId: string): Promise<void>;
+}
+
 /** An environment variable attached to an organization, application, or environment. */
 interface EnvVar {
     /** Unique identifier. */
@@ -531,6 +608,39 @@ interface UpdateEnvVarInput {
     /** Change the sensitive flag. */
     sensitive?: boolean;
 }
+/**
+ * A resolved environment variable returned by the pull endpoint. Only
+ * non-sensitive variables are returned, so {@link value} is always the real value.
+ */
+interface ResolvedEnvVar {
+    /** The variable name (e.g. `DATABASE_URL`). */
+    key: string;
+    /** The resolved variable value. */
+    value: string;
+    /** Where the resolved value came from after applying org → app → environment inheritance. */
+    source: 'organization' | 'application' | 'environment';
+}
+/** Query options for {@link ApplicationEnvVarsResource.pull}. */
+interface PullEnvVarsQuery {
+    /**
+     * Resolve environment-specific overrides for this environment slug on top of
+     * the organization and application baseline. Omit for the local development
+     * baseline (organization + application-wide variables only).
+     */
+    environment?: string;
+}
+/** Result of pulling resolved environment variables for local development. */
+interface PullEnvVarsResult {
+    /** Resolved, non-sensitive variables, ready to write to a local `.env` file. */
+    items: ResolvedEnvVar[];
+    /** Number of resolved variables returned. */
+    total: number;
+    /**
+     * Number of sensitive variables that were resolved but intentionally omitted.
+     * Secrets are never returned by the pull endpoint.
+     */
+    omittedSensitive: number;
+}
 
 /**
  * Manage environment variables scoped to an application.
@@ -552,6 +662,23 @@ declare class ApplicationEnvVarsResource extends BaseResource {
      * ```
      */
     list(applicationId: string, query?: ListQuery): Promise<Paginated<EnvVar>>;
+    /**
+     * Pull the environment variables that apply to an application for local
+     * development. Merges organization-wide, application-wide, and (optionally)
+     * environment-specific overrides, returning only non-sensitive values — ready
+     * to write to a local `.env` file.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param query - Optional environment targeting.
+     * @returns The resolved non-sensitive variables plus the count of omitted secrets.
+     *
+     * @example
+     * ```ts
+     * const { items } = await client.applications.envVars.pull('app-id');
+     * const dotenv = items.map((v) => `${v.key}=${v.value}`).join('\n');
+     * ```
+     */
+    pull(applicationId: string, query?: PullEnvVarsQuery): Promise<PullEnvVarsResult>;
     /**
      * Create a new environment variable for an application.
      *
@@ -1738,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). */
@@ -1753,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}.
  *
@@ -1791,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.
@@ -1805,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}. */
@@ -2383,6 +2763,8 @@ declare class GigadriveClient {
     readonly deployments: DeploymentsResource;
     /** AI Gateway — OpenAI-compatible chat completions and model listing. */
     readonly aiGateway: AiGatewayResource;
+    /** Application-scoped API key management (create, list, revoke). */
+    readonly apiKeys: ApiKeysResource;
     constructor(config?: GigadriveClientConfig);
 }
 
@@ -2521,4 +2903,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 Application, ApplicationEnvVarsResource, type ApplicationHostnameList, ApplicationRequestsResource, ApplicationStorageResource, ApplicationsResource, AuthenticationError, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionContentPart, type ChatCompletionMessage, type ChatCompletionRequest, type ChatCompletionResponse, type ChatCompletionUsage, 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 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 QueryValue, 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 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 };