import type { Application } from "../_internal/types.gen"; import type { RequestOptions } from "../base-client"; import { RequestBuilder } from "../request-builder"; /** * OAuth configuration embedded on an Application. * * ## Schema * * | Field | Type | Sensitive | Notes | * |-------|------|-----------|-------| * | `callback_urls` | `string[]` | No | Allowed OAuth callback URLs. Default `[]`. | * | `default_callback_url` | `string \| null` | No | Default callback URL if not specified in OAuth request. Must be in `callback_urls`. | * | `enabled_providers` | `("google" \| "github" \| "salesforce" \| "microsoft")[]` | No | Providers enabled for this app. Default `["google", "github"]`. | * | `google_client_id` | `string \| null` | No | White-label Google OAuth client ID. Requires `google_client_secret`. | * | `google_client_secret` | `string \| null` | **Yes** | White-label Google OAuth client secret. Write-only at rest. | * | `github_client_id` | `string \| null` | No | White-label GitHub OAuth client ID. Requires `github_client_secret`. | * | `github_client_secret` | `string \| null` | **Yes** | White-label GitHub OAuth client secret. Write-only at rest. | * | `microsoft_client_id` | `string \| null` | No | White-label Microsoft OAuth client ID. Requires `microsoft_client_secret`. | * | `microsoft_client_secret` | `string \| null` | **Yes** | White-label Microsoft OAuth client secret. Write-only at rest. | * * **Validation rules:** * - `default_callback_url` must appear in `callback_urls` when set. * - White-label credentials (client_id/client_secret) must be supplied as a * pair — providing one without the other is rejected. */ export interface OAuthConfig { /** Allowed OAuth redirect callback URLs. */ callback_urls?: string[] | null; /** Default callback URL when the OAuth request omits one. Must be in `callback_urls`. */ default_callback_url?: string | null; /** OAuth providers enabled for this application. */ enabled_providers?: Array<"google" | "github" | "salesforce" | "microsoft"> | null; /** White-label Google OAuth client ID (optional). Requires `google_client_secret`. */ google_client_id?: string | null; /** * White-label Google OAuth client secret (optional). Requires `google_client_id`. * Sensitive — never returned in read responses. */ google_client_secret?: string | null; /** White-label GitHub OAuth client ID (optional). Requires `github_client_secret`. */ github_client_id?: string | null; /** * White-label GitHub OAuth client secret (optional). Requires `github_client_id`. * Sensitive — never returned in read responses. */ github_client_secret?: string | null; /** White-label Microsoft OAuth client ID (optional). Requires `microsoft_client_secret`. */ microsoft_client_id?: string | null; /** * White-label Microsoft OAuth client secret (optional). Requires `microsoft_client_id`. * Sensitive — never returned in read responses. */ microsoft_client_secret?: string | null; } /** * Result shape returned by the `:read_current` action (`GET /applications/current` * and `GET /applications/me`). This is a plain map wrapped in an action-result * envelope rather than a full JSON:API resource — it includes `owner_id` and * all application configuration fields. * * Note: `generated_api_key` is populated only on `:create` and is always `null` * here. Use `admin.applications.create()` or the `createApiKey` action to * obtain a new key. */ export interface CurrentApplicationResult { id: string; name: string; slug: string; description: string | null; invite_only: boolean; base_url: string; logo_url: string | null; badge_url: string | null; sender_name: string | null; sender_email: string | null; require_email_verification: boolean; vanity_slug: string | null; /** OAuth provider configuration. See `OAuthConfig` for full field schema. */ oauth: OAuthConfig | null; workspace_mode: "single" | "multi"; invitation_mode: "open" | "admin_only"; allow_org_creation: boolean; /** * Enabled platform feature gates for this application. * * Capability strings are bundle keys (e.g. `"crm"`, `"agents"`, * `"intelligence"`) or the opt-in `"ai_workload_routing"`. Call * `GET /isv/capabilities` for the complete list. */ enabled_capabilities: string[] | null; /** * Regulatory/data-handling attestations for this application. * * Valid values include `"GDPR"`, `"HIPAA"`, `"SOC2"`, `"PCI-DSS"`, * `"SOC2-Type2"`, `"ISO27001"`, and `"NIST800-53"`. Tags enable * compliance-specific safeguards such as HIPAA session timeouts, BAA-safe * provider routing, telemetry redaction, and webhook/body handling. */ compliance_tags: string[] | null; capability_schema_version: number | null; default_free_credits: number; max_concurrent_executions_per_tenant: number; max_concurrent_executions_per_workspace: number; max_parallel_tools_global: number | null; payment_provider: "qorpay" | "stripe"; portal_defaults: Record | null; public_registry: boolean | null; /** * How auth-related emails are delivered. * - `"link"`: emails contain a click-through URL anchored on `base_url` * - `"code"`: emails contain a paste-able 6-character code */ system_email_method: "link" | "code"; /** Per-workspace concurrent voice session cap. `null` indicates the * platform default (10) applies. */ voice_max_sessions_per_workspace: number | null; /** Voice session auto-timeout in minutes. `null` indicates the platform * default (30) applies. */ voice_session_timeout_minutes: number | null; /** Additional ops/finance contacts for Layer 1 billing communications. */ billing_contact_emails: string[]; /** UUID of the Tenant that owns this application. */ owner_id: string | null; created_at: string; updated_at: string; } /** Attributes accepted by `POST /admin/applications` (create). */ export interface CreateApplicationAttributes { /** Display name of the application. */ name: string; /** URL-friendly identifier. Auto-generated from name if omitted. */ slug?: string; /** Human-readable description of the application. */ description?: string; /** UUID of the user who owns this application. */ owner_id: string; /** Free credits granted to each new tenant on signup. Default: 0. */ default_free_credits?: number; /** URL to the application logo image. */ logo_url?: string; /** URL to the application badge image. */ badge_url?: string; /** Whether new users must verify their email before accessing the application. */ require_email_verification?: boolean; /** Base URL for the application (used in emails, OAuth redirects, etc.). */ base_url?: string; /** Display name for outbound emails from this application. */ sender_name?: string; /** Email address for outbound emails from this application. */ sender_email?: string; /** Whether the application requires an invitation to join. */ invite_only?: boolean; /** OAuth provider configuration. See `OAuthConfig` for the full field schema. */ oauth?: OAuthConfig; /** Custom vanity slug for the application portal URL. */ vanity_slug?: string; /** * Platform capabilities to enable for this application. * * Capability strings are bundle keys (e.g. `"crm"`, `"agents"`, * `"intelligence"`) or the opt-in `"ai_workload_routing"`. Use * `admin.capabilities.list()` to discover the complete list. Bundle * membership is structural — there is no automatic dependency expansion, * so each bundle the application needs must be listed explicitly. */ enabled_capabilities?: string[]; /** * Workspace isolation mode. * - `"single"` (default): One workspace per tenant, auto-resolved. Callers never pass workspace_id. * - `"multi"`: Tenants manage workspaces explicitly. workspace_id required on scoped requests. */ workspace_mode?: "single" | "multi"; /** Write-only — accepted on create but never returned in responses (encrypted at rest). Per-capability configuration keys. */ capability_config?: Record; /** Whether tenants can create sub-organizations. */ allow_org_creation?: boolean; /** Controls who can send invitations. `"open"` allows any member; `"admin_only"` restricts to tenant admins. */ invitation_mode?: "open" | "admin_only"; /** Payment provider for billing integration. */ payment_provider?: "qorpay" | "stripe"; /** Default portal configuration for new tenants (theme, layout, feature visibility). */ portal_defaults?: Record; /** When true, the application's registry at `/r/{app_slug}/` is publicly * readable without a token. Default: false. */ public_registry?: boolean; /** How auth-related emails are delivered. Default: `"link"`. */ system_email_method?: "link" | "code"; /** * Additional ops/finance contacts for Layer 1 billing communications * (overdraft warnings, suspension notices, payout failures). The * application owner is notified separately and does not need to be * listed here. */ billing_contact_emails?: string[]; } /** Attributes accepted by `PATCH /admin/applications/:id` (update). */ export interface UpdateApplicationAttributes { name?: string; slug?: string; description?: string; logo_url?: string | null; badge_url?: string | null; base_url?: string; sender_name?: string; sender_email?: string; require_email_verification?: boolean; invite_only?: boolean; /** OAuth provider configuration. See `OAuthConfig` for the full field schema. */ oauth?: OAuthConfig; vanity_slug?: string | null; /** * Platform capabilities to enable for this application. * * Preserve existing capability strings when adding or removing one bundle. * Capability strings are bundle keys (e.g. `"crm"`, `"agents"`, * `"intelligence"`) or the opt-in `"ai_workload_routing"`. Use * `admin.capabilities.list()` for the complete list. */ enabled_capabilities?: string[]; workspace_mode?: "single" | "multi"; /** Write-only — accepted on update but never returned in responses (encrypted at rest). */ capability_config?: Record; allow_org_creation?: boolean; invitation_mode?: "open" | "admin_only"; max_parallel_tools_global?: number; /** Per-workspace ceiling on concurrent agent executions (default 10). */ max_concurrent_executions_per_workspace?: number; /** Per-tenant ceiling on concurrent agent executions (default 50). */ max_concurrent_executions_per_tenant?: number; payment_provider?: "qorpay" | "stripe"; portal_defaults?: Record; /** Allowed source IPs for server-side keys (CIDR strings). */ allowed_server_ips?: string[]; /** Failed-login attempts permitted per window before lockout (default 5). */ login_lockout_threshold?: number; /** Sliding window in seconds for login-lockout counting (default 900). */ login_lockout_window_seconds?: number; /** Lockout duration in seconds once threshold is hit (default 900). */ login_lockout_duration_seconds?: number; /** Update how auth-related emails are delivered. */ system_email_method?: "link" | "code"; /** * Multi-tier MFA enforcement policy (D1). * * - `"required"`: every user must complete MFA at login. * - `"tenant_choice"`: defer to each tenant's `mfa_policy`; login-time * aggregate fires if ANY user tenant under this app has `mfa_policy: "required"`. * - `"user_choice"`: defer to per-user opt-in (default). */ mfa_policy?: "required" | "tenant_choice" | "user_choice"; /** * Whether the application's registry at `/r/{app_slug}/` is publicly * readable without a token. Updating this immediately changes registry * visibility for new requests (the Application cache is invalidated by * the server on update). */ public_registry?: boolean; /** * Per-workspace concurrent voice session cap. `null` resets to the * platform default (10). Server invalidates the Application cache so * the new ceiling takes effect without a redeploy. */ voice_max_sessions_per_workspace?: number | null; /** * Voice session auto-timeout in minutes. `null` resets to the platform * default (30). Server invalidates the Application cache so the new * timeout takes effect without a redeploy. */ voice_session_timeout_minutes?: number | null; /** * Additional ops/finance contacts for Layer 1 billing communications. * Replaces the existing list — pass `[]` to clear all contacts. */ billing_contact_emails?: string[]; } /** * ISV application management — create, configure, and manage platform applications. * * Applications are the top-level identity for ISV products. Each application * owns tenants, API keys, capability configs, and billing accounts. */ export declare function createApplicationsNamespace(rb: RequestBuilder): { /** * Lists all applications on the platform. * * @param options - Optional request options (headers, abort signal). * @returns Array of Application objects. * * @example * ```ts * const apps = await admin.applications.list(); * ``` */ list: (options?: RequestOptions) => Promise; /** * Fetches a single application by ID. * * @param id - Application UUID. * @param options - Optional request options. * @returns The Application record. * * @example * ```ts * const app = await admin.applications.get("uuid"); * ``` */ get: (id: string, options?: RequestOptions) => Promise; /** * Fetches an application by its unique slug. * * @param slug - Application slug (e.g. "my-saas-app"). * @param options - Optional request options. * @returns The Application record. * * @example * ```ts * const app = await admin.applications.getBySlug("my-saas-app"); * ``` */ getBySlug: (slug: string, options?: RequestOptions) => Promise; /** * Fetches the application associated with the current API key. * * Resolves the application from the `x-application-key` header. * Returns a 30-field projection including `owner_id` and all capability * configuration. Useful for validating API key connectivity and reading * ISV configuration at runtime. * * @param options - Optional request options. * @returns The current application as a `CurrentApplicationResult` map. * * @example * ```ts * const app = await admin.applications.getCurrent(); * console.log(app.owner_id); // tenant UUID * ``` */ getCurrent: (options?: RequestOptions) => Promise; /** * Alias for `getCurrent()` — fetches the application for the current API key. * * Calls `GET /admin/applications/me`. Returns the same 30-field projection * as `getCurrent()`, including `owner_id`. * * @param options - Optional request options. * @returns The current application as a `CurrentApplicationResult` map. * * @example * ```ts * const app = await admin.applications.getMe(); * ``` */ getMe: (options?: RequestOptions) => Promise; /** * Registers a new ISV application on the platform. * * Auto-generates a unique slug from name if not provided. Validates * enabled_capabilities and their dependency graph. After creation: * creates a billing liability account, auto-generates a default * `sk_app_` API key (returned once in `generated_api_key`), and * creates system email templates. * * @param attrs - Application creation attributes. * @param options - Optional request options. * @returns The created Application with `generated_api_key` populated (one-time). * * @example * ```ts * const app = await admin.applications.create({ * name: "My SaaS App", * owner_id: "tenant-uuid", * base_url: "https://app.example.com", * }); * console.log(app.attributes.generated_api_key); // Save this! * ``` */ create: (attrs: CreateApplicationAttributes, options?: RequestOptions) => Promise; /** * Updates an existing application's configuration. * * Accepts branding, email settings, capability flags, workspace mode, * and execution limits. Validates enabled_capabilities and their * dependency graph. Use `updateComplianceTags` for compliance tag * changes, and `allocateCredits` for funding. * * @param id - Application UUID. * @param attrs - Attributes to update. * @param options - Optional request options. * @returns The updated Application. * * @example * ```ts * // Tune execution + onboarding settings * const app = await admin.applications.update("uuid", { * max_parallel_tools_global: 10, * invite_only: true, * }); * * // Switch the application's auth emails to short-code mode (required * // for ISVs without a hosted website at base_url, e.g., the SF plugin). * // Per-call overrides on `register` and `invitations.create` continue * // to take precedence over this Application-level default. * const app = await admin.applications.update("uuid", { * system_email_method: "code", * }); * ``` */ update: (id: string, attrs: UpdateApplicationAttributes, options?: RequestOptions) => Promise; /** * Deletes an application. * * @param id - Application UUID. * @param options - Optional request options. * @returns `true` on success. * * @example * ```ts * await admin.applications.delete("uuid"); * ``` */ delete: (id: string, options?: RequestOptions) => Promise; /** * Sets compliance tags on an application (platform admin only). * * Compliance tags indicate regulatory frameworks the application * adheres to (e.g. GDPR, HIPAA, SOC2). Tags drive data-handling controls * such as HIPAA session timeouts, BAA-safe provider routing, telemetry * redaction, and webhook/body handling. * * This is a dedicated action separate from the general update to enforce * platform-admin-only access. * * @param id - Application UUID. * @param complianceTags - Array of compliance tag strings. * @param options - Optional request options. * @returns The updated Application. * * @example * ```ts * const app = await admin.applications.updateComplianceTags("uuid", [ * "GDPR", * "HIPAA", * "SOC2", * ]); * ``` */ updateComplianceTags: (id: string, complianceTags: string[], options?: RequestOptions) => Promise; /** * Grants credits to the application's billing account. * * @param id - Application UUID. * @param amount - Number of credits to grant. * @param tenantId - Target tenant UUID for credit allocation. * @param options - Optional request options. * @returns The updated Application. * * @example * ```ts * const app = await admin.applications.grantCredits("app-uuid", 1000, "tenant-uuid"); * ``` */ grantCredits: (id: string, amount: number, tenantId: string, options?: RequestOptions) => Promise; /** * Allocates credits from the application's account to a tenant. * * @param id - Application UUID. * @param amount - Number of credits to allocate to the application's own billing account. * @param description - Optional description for the credit transaction. * @param options - Optional request options. * @returns The updated Application. * * @example * ```ts * const app = await admin.applications.allocateCredits("app-uuid", 500); * ``` */ allocateCredits: (id: string, amount: number, description?: string, options?: RequestOptions) => Promise; /** * Atomically provision an ISV Application — Aggregate authoring (§4.10.5). * * Composes Application + (optional) BrandIdentity + (optional) * EmailTemplate overrides + (optional) initial WholesaleAgreement in a * single transaction. `Application.:create`'s after-actions still run * inside the transaction, so the new Application also gets a billing * liability account, a default `sk_app_` API key, system email templates, * and system legal documents automatically. * * **Idempotency:** keyed on `spec.slug`. Re-running with the same slug * returns `status: "unchanged"` with the existing entity ids — no new * BrandIdentity / EmailTemplate / WholesaleAgreement rows are written. * * **Authorization:** any authenticated caller may call this endpoint. * The inner `Application.:create` enforces `IsIsvTenantOwner` against * `spec.owner_id` and rolls the entire transaction back if the actor * doesn't own/admin that tenant. `initial_wholesale_agreement` is * platform-admin-only; non-admin callers are rejected up-front with * `wholesale_agreement_requires_platform_admin`. * * @param spec - Application provisioning spec (see ApplicationProvisionSpec). * @param options - Optional request options. * @returns Provision result with `status` + per-entity ids. * * @example * ```typescript * // ISV self-serve provision (no WholesaleAgreement). * const result = await admin.applications.provision({ * name: "My SaaS", * slug: "my-saas", * owner_id: "tenant-uuid", * workspace_mode: "single", * payment_provider: "qorpay", * brand_identity: { * voice: "Friendly but precise", * values: ["clarity", "trust"], * logo_url: "https://example.com/logo.png", * }, * initial_bundles: ["crm", "scheduling"], * email_templates: { * invitation: { subject: "Join {{scope.name}}!" }, * }, * }); * console.log(result.entity_ids.application_id); * ``` */ provision: (spec: ApplicationProvisionSpec, options?: RequestOptions) => Promise; }; /** * Spec accepted by `admin.applications.provision()`. Loose-typed nested * objects mirror the server-side Ash resources — see * `lib/gpt_core/tenancy/services/application_provisioner.ex` for the * authoritative shape. */ export interface ApplicationProvisionSpec { /** Required. Display name. */ name: string; /** Required. URL-safe identifier, also the idempotency key. */ slug: string; /** Required. ISV tenant id that will own the new Application. */ owner_id: string; description?: string; logo_url?: string; badge_url?: string; base_url?: string; sender_name?: string; sender_email?: string; workspace_mode?: "single" | "multi"; payment_provider?: "qorpay" | "stripe"; billing_contact_emails?: string[]; system_email_method?: "link" | "code"; mfa_policy?: "required" | "tenant_choice" | "user_choice"; invitation_mode?: "open" | "admin_only"; allow_org_creation?: boolean; require_email_verification?: boolean; default_free_credits?: number; vanity_slug?: string; oauth?: OAuthConfig; public_registry?: boolean; allowed_server_ips?: string[]; portal_defaults?: { [key: string]: unknown; }; compliance_tags?: string[]; /** Bundle keys to enable. Defaults to the standard bundle set when omitted. */ initial_bundles?: string[]; /** * Optional tenant-scoped BrandIdentity to create alongside the Application. * Skipped on idempotent re-run. */ brand_identity?: { voice?: string; values?: string[]; target_audience?: string; industry?: string; website_url?: string; logo_url?: string; color_palette?: { [key: string]: unknown; }; description?: string; [key: string]: unknown; }; /** * ISV overrides for system email templates (keyed by template slug, e.g. * `"invitation"`, `"verification"`, `"password_reset"`). Skipped on * idempotent re-run. */ email_templates?: { [slug: string]: { subject?: string; body_markdown?: string; primary_color?: string; name?: string; enabled?: boolean; }; }; /** * Optional initial commercial WholesaleAgreement. **Platform-admin-only.** * Non-admin callers receive a `wholesale_agreement_requires_platform_admin` * error and the whole provision is rejected up-front. */ initial_wholesale_agreement?: { permitted_capability_tiers?: string[]; overdraft_limit_credits?: number; refund_reversal_days?: number; settlement_frequency?: string; effective_date?: string; notes?: string; [key: string]: unknown; }; } /** Result envelope returned by `admin.applications.provision()`. */ export interface ApplicationProvisionResult { status: "created" | "unchanged"; entity_ids: { application_id: string; brand_identity_id: string | null; email_template_ids: string[]; wholesale_agreement_id: string | null; }; } //# sourceMappingURL=applications.d.ts.map