diff --git a/docs/sdk/cli-reference.md b/docs/sdk/cli-reference.md index c5444c0..30c390f 100644 --- a/docs/sdk/cli-reference.md +++ b/docs/sdk/cli-reference.md @@ -87,160 +87,177 @@ Workspace ID resolution follows this priority order: ## Commands + + ### [Application Commands](cli/application) Commands for managing Tailor Platform applications (work with `tailor.config.ts`). -| Command | Description | -| ----------------------------------------- | --------------------------------- | -| [init](cli/application.md#init) | Initialize a new project | -| [generate](cli/application.md#generate) | Generate files from configuration | -| [apply](cli/application.md#apply) | Deploy application to workspace | -| [remove](cli/application.md#remove) | Remove application from workspace | -| [show](cli/application.md#show) | Show deployed application info | +| Command | Description | +| ----------------------------------------- | ------------------------------------------------------------------- | +| [init](cli/application.md#init) | Initialize a new project using create-sdk. | +| [generate](cli/application.md#generate) | Generate files using Tailor configuration. | +| [apply](cli/application.md#apply) | Apply Tailor configuration to deploy your application. | +| [remove](cli/application.md#remove) | Remove all resources managed by the application from the workspace. | +| [show](cli/application.md#show) | Show information about the deployed application. | +| [open](cli/application.md#open) | Open Tailor Platform Console. | +| [api](cli/application.md#api) | Call Tailor Platform API endpoints directly. | ### [TailorDB Commands](cli/tailordb) Commands for managing TailorDB tables, data, and schema migrations. -| Command | Description | -| ---------------------------------------------------------------------------- | ------------------------------------------------ | -| [tailordb truncate](cli/tailordb.md#tailordb-truncate) | Truncate TailorDB tables | -| [tailordb migration generate](cli/tailordb.md#tailordb-migration-generate) | Generate migration files from schema snapshot | -| [tailordb migration set](cli/tailordb.md#tailordb-migration-set) | Set migration checkpoint manually | -| [tailordb migration status](cli/tailordb.md#tailordb-migration-status) | Show migration status | -| [tailordb erd export](cli/tailordb.md#tailordb-erd-export) | Export ERD artifacts from TailorDB schema (beta) | -| [tailordb erd serve](cli/tailordb.md#tailordb-erd-serve) | Serve ERD locally (beta) | -| [tailordb erd deploy](cli/tailordb.md#tailordb-erd-deploy) | Deploy ERD static website (beta) | - -Note: Migration scripts are automatically executed during `tailor-sdk apply`. See [Automatic Migration Execution](cli/tailordb.md#automatic-migration-execution) for details. +| Command | Description | +| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| [tailordb truncate](cli/tailordb.md#tailordb-truncate) | Truncate (delete all records from) TailorDB tables. | +| [tailordb migration generate](cli/tailordb.md#tailordb-migration-generate) | Generate migration files by detecting schema differences between current local types and the previous migration snapshot. | +| [tailordb migration set](cli/tailordb.md#tailordb-migration-set) | Set migration checkpoint to a specific number. | +| [tailordb migration status](cli/tailordb.md#tailordb-migration-status) | Show the current migration status for TailorDB namespaces, including applied and pending migrations. | +| [tailordb erd export](cli/tailordb.md#tailordb-erd-export) | Export Liam ERD dist from applied TailorDB schema. | +| [tailordb erd serve](cli/tailordb.md#tailordb-erd-serve) | Generate and serve ERD locally (liam build + serve dist). (beta) | +| [tailordb erd deploy](cli/tailordb.md#tailordb-erd-deploy) | Deploy ERD static website for TailorDB namespace(s). | ### [User & Auth Commands](cli/user) Commands for authentication and user management. -| Command | Description | -| ------------------------------------------------ | ------------------------------ | -| [login](cli/user.md#login) | Login to Tailor Platform | -| [logout](cli/user.md#logout) | Logout from Tailor Platform | -| [user current](cli/user.md#user-current) | Show current user | -| [user list](cli/user.md#user-list) | List all users | -| [user switch](cli/user.md#user-switch) | Set current user | -| [user pat list](cli/user.md#user-pat-list) | List personal access tokens | -| [user pat create](cli/user.md#user-pat-create) | Create a personal access token | -| [user pat delete](cli/user.md#user-pat-delete) | Delete a personal access token | -| [user pat update](cli/user.md#user-pat-update) | Update a personal access token | - -### Workspace & Organization Commands - -Commands for managing workspaces, profiles, organizations, and folders. - -**[Organization Commands](cli/organization)** - -| Command | Description | -| ------------------------------------------------------------------------------ | ----------------------------------------------- | -| [organization list](cli/organization.md#organization-list) | List organizations you belong to | -| [organization get](cli/organization.md#organization-get) | Show detailed information about an organization | -| [organization update](cli/organization.md#organization-update) | Update an organization's name | -| [organization tree](cli/organization.md#organization-tree) | Display organization folder hierarchy as a tree | -| [organization folder list](cli/organization.md#organization-folder-list) | List folders in an organization | -| [organization folder get](cli/organization.md#organization-folder-get) | Show detailed information about a folder | -| [organization folder create](cli/organization.md#organization-folder-create) | Create a new folder in an organization | -| [organization folder update](cli/organization.md#organization-folder-update) | Update a folder's name | -| [organization folder delete](cli/organization.md#organization-folder-delete) | Delete a folder from an organization | - -**[Workspace Commands](cli/workspace)** - -| Command | Description | -| ------------------------------------------------------- | ---------------------- | -| [workspace create](cli/workspace.md#workspace-create) | Create a new workspace | -| [workspace list](cli/workspace.md#workspace-list) | List all workspaces | -| [workspace delete](cli/workspace.md#workspace-delete) | Delete a workspace | -| [profile create](cli/workspace.md#profile-create) | Create a new profile | -| [profile list](cli/workspace.md#profile-list) | List all profiles | -| [profile update](cli/workspace.md#profile-update) | Update a profile | -| [profile delete](cli/workspace.md#profile-delete) | Delete a profile | +| Command | Description | +| ------------------------------------------------ | ----------------------------------------------------- | +| [login](cli/user.md#login) | Login to Tailor Platform. | +| [logout](cli/user.md#logout) | Logout from Tailor Platform. | +| [user current](cli/user.md#user-current) | Show current user. | +| [user list](cli/user.md#user-list) | List all users. | +| [user switch](cli/user.md#user-switch) | Set current user. | +| [user pat list](cli/user.md#user-pat-list) | List all personal access tokens. | +| [user pat create](cli/user.md#user-pat-create) | Create a new personal access token. | +| [user pat delete](cli/user.md#user-pat-delete) | Delete a personal access token. | +| [user pat update](cli/user.md#user-pat-update) | Update a personal access token (delete and recreate). | + +### [Organization Commands](cli/organization) + +Commands for managing organizations and folders. + +| Command | Description | +| ------------------------------------------------------------------------------ | ------------------------------------------------ | +| [organization folder create](cli/organization.md#organization-folder-create) | Create a new folder in an organization. | +| [organization folder delete](cli/organization.md#organization-folder-delete) | Delete a folder from an organization. | +| [organization folder get](cli/organization.md#organization-folder-get) | Show detailed information about a folder. | +| [organization folder list](cli/organization.md#organization-folder-list) | List folders in an organization. | +| [organization folder update](cli/organization.md#organization-folder-update) | Update a folder's name. | +| [organization get](cli/organization.md#organization-get) | Show detailed information about an organization. | +| [organization list](cli/organization.md#organization-list) | List organizations you belong to. | +| [organization tree](cli/organization.md#organization-tree) | Display organization folder hierarchy as a tree. | +| [organization update](cli/organization.md#organization-update) | Update an organization's name. | + +### [Workspace Commands](cli/workspace) + +Commands for managing workspaces and profiles. + +| Command | Description | +| ----------------------------------------------------------------- | ------------------------------------------- | +| [workspace app health](cli/workspace.md#workspace-app-health) | Check application schema health | +| [workspace app list](cli/workspace.md#workspace-app-list) | List applications in a workspace | +| [workspace create](cli/workspace.md#workspace-create) | Create a new Tailor Platform workspace. | +| [workspace delete](cli/workspace.md#workspace-delete) | Delete a Tailor Platform workspace. | +| [workspace get](cli/workspace.md#workspace-get) | Show detailed information about a workspace | +| [workspace list](cli/workspace.md#workspace-list) | List all Tailor Platform workspaces. | +| [workspace restore](cli/workspace.md#workspace-restore) | Restore a deleted workspace | +| [workspace user invite](cli/workspace.md#workspace-user-invite) | Invite a user to a workspace | +| [workspace user list](cli/workspace.md#workspace-user-list) | List users in a workspace | +| [workspace user remove](cli/workspace.md#workspace-user-remove) | Remove a user from a workspace | +| [workspace user update](cli/workspace.md#workspace-user-update) | Update a user's role in a workspace | +| [profile create](cli/workspace.md#profile-create) | Create a new profile. | +| [profile delete](cli/workspace.md#profile-delete) | Delete a profile. | +| [profile list](cli/workspace.md#profile-list) | List all profiles. | +| [profile update](cli/workspace.md#profile-update) | Update profile properties. | ### [Auth Resource Commands](cli/auth) Commands for managing Auth service resources. -| Command | Description | -| ---------------------------------------------------- | ----------------------------- | -| [machineuser list](cli/auth.md#machineuser-list) | List machine users | -| [machineuser token](cli/auth.md#machineuser-token) | Get machine user access token | -| [oauth2client list](cli/auth.md#oauth2client-list) | List OAuth2 clients | -| [oauth2client get](cli/auth.md#oauth2client-get) | Get OAuth2 client credentials | +| Command | Description | +| ------------------------------------------------------------------ | -------------------------------------------------------- | +| [authconnection authorize](cli/auth.md#authconnection-authorize) | Authorize an auth connection via OAuth2 flow. | +| [authconnection list](cli/auth.md#authconnection-list) | List all auth connections. | +| [authconnection revoke](cli/auth.md#authconnection-revoke) | Revoke an auth connection. | +| [machineuser list](cli/auth.md#machineuser-list) | List all machine users in the application. | +| [machineuser token](cli/auth.md#machineuser-token) | Get an access token for a machine user. | +| [oauth2client list](cli/auth.md#oauth2client-list) | List all OAuth2 clients in the application. | +| [oauth2client get](cli/auth.md#oauth2client-get) | Get OAuth2 client credentials (including client secret). | ### [Workflow Commands](cli/workflow) Commands for managing workflows and executions. -| Command | Description | -| ------------------------------------------------------------ | -------------------------- | -| [workflow list](cli/workflow.md#workflow-list) | List all workflows | -| [workflow get](cli/workflow.md#workflow-get) | Get workflow details | -| [workflow start](cli/workflow.md#workflow-start) | Start a workflow execution | -| [workflow executions](cli/workflow.md#workflow-executions) | List or get executions | -| [workflow resume](cli/workflow.md#workflow-resume) | Resume a failed execution | +| Command | Description | +| ------------------------------------------------------------ | ---------------------------------------------- | +| [workflow list](cli/workflow.md#workflow-list) | List all workflows in the workspace. | +| [workflow get](cli/workflow.md#workflow-get) | Get workflow details. | +| [workflow start](cli/workflow.md#workflow-start) | Start a workflow execution. | +| [workflow executions](cli/workflow.md#workflow-executions) | List or get workflow executions. | +| [workflow resume](cli/workflow.md#workflow-resume) | Resume a failed or pending workflow execution. | ### [Function Commands](cli/function) Commands for viewing function execution logs. -| Command | Description | -| ------------------------------------------------ | ----------------------------------- | -| [function logs](cli/function.md#function-logs) | List or get function execution logs | +| Command | Description | +| -------------------------------------------------------- | --------------------------------------------------------------- | +| [function logs](cli/function.md#function-logs) | List or get function execution logs. | +| [function test-run](cli/function.md#function-test-run) | Run a function on the Tailor Platform server without deploying. | ### [Executor Commands](cli/executor) Commands for managing executors and executor jobs. -| Command | Description | -| ------------------------------------------------------ | ---------------------------- | -| [executor trigger](cli/executor.md#executor-trigger) | Trigger an executor manually | -| [executor jobs](cli/executor.md#executor-jobs) | List or get executor jobs | +| Command | Description | +| ---------------------------------------------------------------- | --------------------------------------------- | +| [executor trigger](cli/executor.md#executor-trigger) | Trigger an executor manually. | +| [executor jobs](cli/executor.md#executor-jobs) | List or get executor jobs. | +| [executor list](cli/executor.md#executor-list) | List all executors | +| [executor get](cli/executor.md#executor-get) | Get executor details | +| [executor webhook list](cli/executor.md#executor-webhook-list) | List executors with incoming webhook triggers | ### [Secret Commands](cli/secret) Commands for managing secrets and vaults. -| Command | Description | -| ---------------------------------------------------------- | ----------------------- | -| [secret vault create](cli/secret.md#secret-vault-create) | Create a vault | -| [secret vault delete](cli/secret.md#secret-vault-delete) | Delete a vault | -| [secret vault list](cli/secret.md#secret-vault-list) | List all vaults | -| [secret create](cli/secret.md#secret-create) | Create a secret | -| [secret update](cli/secret.md#secret-update) | Update a secret | -| [secret list](cli/secret.md#secret-list) | List secrets in a vault | -| [secret delete](cli/secret.md#secret-delete) | Delete a secret | +| Command | Description | +| ---------------------------------------------------------- | ------------------------------------------------ | +| [secret vault create](cli/secret.md#secret-vault-create) | Create a new Secret Manager vault. | +| [secret vault delete](cli/secret.md#secret-vault-delete) | Delete a Secret Manager vault. | +| [secret vault list](cli/secret.md#secret-vault-list) | List all Secret Manager vaults in the workspace. | +| [secret create](cli/secret.md#secret-create) | Create a secret in a vault. | +| [secret update](cli/secret.md#secret-update) | Update a secret in a vault. | +| [secret list](cli/secret.md#secret-list) | List all secrets in a vault. | +| [secret delete](cli/secret.md#secret-delete) | Delete a secret in a vault. | ### [Static Website Commands](cli/staticwebsite) Commands for managing and deploying static websites. -| Command | Description | -| ------------------------------------------------------------------- | ---------------------------------------------------- | -| [staticwebsite deploy](cli/staticwebsite.md#staticwebsite-deploy) | Deploy a static website from a local build directory | -| [staticwebsite list](cli/staticwebsite.md#staticwebsite-list) | List static websites in a workspace | -| [staticwebsite get](cli/staticwebsite.md#staticwebsite-get) | Get details of a static website | +| Command | Description | +| ------------------------------------------------------------------- | ----------------------------------------------------- | +| [staticwebsite deploy](cli/staticwebsite.md#staticwebsite-deploy) | Deploy a static website from a local build directory. | +| [staticwebsite list](cli/staticwebsite.md#staticwebsite-list) | List all static websites in a workspace. | +| [staticwebsite get](cli/staticwebsite.md#staticwebsite-get) | Get details of a specific static website. | ### [Crash Report Commands](cli/crash-report) Commands for managing crash reports. -| Command | Description | -| ------------------------------------------------------------ | --------------------------------------------- | -| [crash-report list](cli/crash-report.md#crash-report-list) | List local crash report files | -| [crash-report send](cli/crash-report.md#crash-report-send) | Submit a crash report to help improve the SDK | +| Command | Description | +| ------------------------------------------------------------ | ---------------------------------------------- | +| [crash-report list](cli/crash-report.md#crash-report-list) | List local crash report files. | +| [crash-report send](cli/crash-report.md#crash-report-send) | Submit a crash report to help improve the SDK. | ### [Setup Commands](cli/setup) Commands for setting up project infrastructure. -| Command | Description | -| ------------------------------------------- | ----------------------------------------------- | -| [setup github](cli/setup.md#setup-github) | Generate GitHub Actions workflow for deployment | +| Command | Description | +| ------------------------------------------- | ------------------------------------------------------- | +| [setup github](cli/setup.md#setup-github) | Generate GitHub Actions workflow for deployment. (beta) | ### [Completion](cli/completion) @@ -249,3 +266,5 @@ Generate shell completion scripts for bash, zsh, and fish. | Command | Description | | -------------------------------------------- | -------------------------------- | | [completion](cli/completion.md#completion) | Generate shell completion script | + + diff --git a/docs/sdk/cli/auth.md b/docs/sdk/cli/auth.md index 1e03030..ffd94bb 100644 --- a/docs/sdk/cli/auth.md +++ b/docs/sdk/cli/auth.md @@ -1,6 +1,167 @@ # Auth Resource Commands -Commands for managing Auth service resources (machine users and OAuth2 clients). +Commands for managing Auth service resources (auth connections, machine users, and OAuth2 clients). + + + +## authconnection + + + + + +Manage auth connections. + + + + + +**Usage** + +``` +tailor-sdk authconnection [command] +``` + + + + + +**Commands** + +| Command | Description | +| ------------------------------------------------------- | --------------------------------------------- | +| [`authconnection authorize`](#authconnection-authorize) | Authorize an auth connection via OAuth2 flow. | +| [`authconnection list`](#authconnection-list) | List all auth connections. | +| [`authconnection revoke`](#authconnection-revoke) | Revoke an auth connection. | + + + + + +See [Global Options](../cli-reference.md#global-options) for options available to all commands. + + + + +### authconnection authorize + + + + + +Authorize an auth connection via OAuth2 flow. + + + + + +**Usage** + +``` +tailor-sdk authconnection authorize [options] +``` + + + + + +**Options** + +| Option | Alias | Description | Required | Default | Env | +| ------------------------------- | ----- | ------------------------------------------ | -------- | ------------------------ | ------------------------------ | +| `--workspace-id ` | `-w` | Workspace ID | No | - | `TAILOR_PLATFORM_WORKSPACE_ID` | +| `--profile ` | `-p` | Workspace profile | No | - | `TAILOR_PLATFORM_PROFILE` | +| `--name ` | `-n` | Auth connection name | Yes | - | - | +| `--scopes ` | - | OAuth2 scopes to request (comma-separated) | No | `"openid,profile,email"` | - | +| `--port ` | - | Local callback server port | No | `8080` | - | +| `--no-browser` | - | Don't open browser automatically | No | `false` | - | + + + + + +See [Global Options](../cli-reference.md#global-options) for options available to all commands. + + + + + +### authconnection list + + + + + +List all auth connections. + + + + + +**Usage** + +``` +tailor-sdk authconnection list [options] +``` + + + + + +**Options** + +| Option | Alias | Description | Required | Default | Env | +| ------------------------------- | ----- | ----------------- | -------- | ------- | ------------------------------ | +| `--workspace-id ` | `-w` | Workspace ID | No | - | `TAILOR_PLATFORM_WORKSPACE_ID` | +| `--profile ` | `-p` | Workspace profile | No | - | `TAILOR_PLATFORM_PROFILE` | + + + + + +See [Global Options](../cli-reference.md#global-options) for options available to all commands. + + + + +### authconnection revoke + + + + + +Revoke an auth connection. + + + + + +**Usage** + +``` +tailor-sdk authconnection revoke [options] +``` + + + + + +**Options** + +| Option | Alias | Description | Required | Default | Env | +| ------------------------------- | ----- | ------------------------- | -------- | ------- | ------------------------------ | +| `--workspace-id ` | `-w` | Workspace ID | No | - | `TAILOR_PLATFORM_WORKSPACE_ID` | +| `--profile ` | `-p` | Workspace profile | No | - | `TAILOR_PLATFORM_PROFILE` | +| `--name ` | `-n` | Auth connection name | Yes | - | - | +| `--yes` | `-y` | Skip confirmation prompts | No | `false` | - | + + + + + +See [Global Options](../cli-reference.md#global-options) for options available to all commands. + + @@ -156,8 +317,8 @@ tailor-sdk oauth2client [command] | Command | Description | | ----------------------------------------- | -------------------------------------------------------- | -| [`oauth2client get`](#oauth2client-get) | Get OAuth2 client credentials (including client secret). | | [`oauth2client list`](#oauth2client-list) | List all OAuth2 clients in the application. | +| [`oauth2client get`](#oauth2client-get) | Get OAuth2 client credentials (including client secret). | diff --git a/docs/sdk/cli/crash-report.md b/docs/sdk/cli/crash-report.md index d8716d3..647a041 100644 --- a/docs/sdk/cli/crash-report.md +++ b/docs/sdk/cli/crash-report.md @@ -36,8 +36,8 @@ See [Global Options](../cli-reference.md#global-options) for options available t | Command | Description | | ----------------------------------------- | ---------------------------------------------- | -| [`crash-report send`](#crash-report-send) | Submit a crash report to help improve the SDK. | | [`crash-report list`](#crash-report-list) | List local crash report files. | +| [`crash-report send`](#crash-report-send) | Submit a crash report to help improve the SDK. | diff --git a/docs/sdk/cli/executor.md b/docs/sdk/cli/executor.md index e3a6e2d..32773cd 100644 --- a/docs/sdk/cli/executor.md +++ b/docs/sdk/cli/executor.md @@ -30,10 +30,10 @@ tailor-sdk executor [command] | Command | Description | | --------------------------------------- | ----------------------------- | +| [`executor trigger`](#executor-trigger) | Trigger an executor manually. | +| [`executor jobs`](#executor-jobs) | List or get executor jobs. | | [`executor list`](#executor-list) | List all executors | | [`executor get`](#executor-get) | Get executor details | -| [`executor jobs`](#executor-jobs) | List or get executor jobs. | -| [`executor trigger`](#executor-trigger) | Trigger an executor manually. | | [`executor webhook`](#executor-webhook) | Manage executor webhooks | diff --git a/docs/sdk/cli/secret.md b/docs/sdk/cli/secret.md index dd1395f..2ebd7f2 100644 --- a/docs/sdk/cli/secret.md +++ b/docs/sdk/cli/secret.md @@ -30,11 +30,11 @@ tailor-sdk secret [command] | Command | Description | | --------------------------------- | ----------------------------- | +| [`secret vault`](#secret-vault) | Manage Secret Manager vaults. | | [`secret create`](#secret-create) | Create a secret in a vault. | -| [`secret delete`](#secret-delete) | Delete a secret in a vault. | -| [`secret list`](#secret-list) | List all secrets in a vault. | | [`secret update`](#secret-update) | Update a secret in a vault. | -| [`secret vault`](#secret-vault) | Manage Secret Manager vaults. | +| [`secret list`](#secret-list) | List all secrets in a vault. | +| [`secret delete`](#secret-delete) | Delete a secret in a vault. | diff --git a/docs/sdk/cli/staticwebsite.md b/docs/sdk/cli/staticwebsite.md index 2860d1a..d5f8fce 100644 --- a/docs/sdk/cli/staticwebsite.md +++ b/docs/sdk/cli/staticwebsite.md @@ -31,8 +31,8 @@ tailor-sdk staticwebsite [command] | Command | Description | | ----------------------------------------------- | ----------------------------------------------------- | | [`staticwebsite deploy`](#staticwebsite-deploy) | Deploy a static website from a local build directory. | -| [`staticwebsite get`](#staticwebsite-get) | Get details of a specific static website. | | [`staticwebsite list`](#staticwebsite-list) | List all static websites in a workspace. | +| [`staticwebsite get`](#staticwebsite-get) | Get details of a specific static website. | diff --git a/docs/sdk/cli/tailordb.md b/docs/sdk/cli/tailordb.md index af62ec7..6727e24 100644 --- a/docs/sdk/cli/tailordb.md +++ b/docs/sdk/cli/tailordb.md @@ -30,9 +30,9 @@ tailor-sdk tailordb [command] | Command | Description | | ------------------------------------------- | --------------------------------------------------------------------- | -| [`tailordb erd`](#tailordb-erd) | Generate ERD artifacts for TailorDB namespaces using Liam ERD. (beta) | -| [`tailordb migration`](#tailordb-migration) | Manage TailorDB schema migrations. | | [`tailordb truncate`](#tailordb-truncate) | Truncate (delete all records from) TailorDB tables. | +| [`tailordb migration`](#tailordb-migration) | Manage TailorDB schema migrations. | +| [`tailordb erd`](#tailordb-erd) | Generate ERD artifacts for TailorDB namespaces using Liam ERD. (beta) | @@ -105,6 +105,8 @@ Manage TailorDB schema migrations. +Note: Migration scripts are automatically executed during `tailor-sdk apply`. See [Automatic Migration Execution](#automatic-migration-execution) for details. + **Usage** diff --git a/docs/sdk/cli/user.md b/docs/sdk/cli/user.md index 32ead06..29da227 100644 --- a/docs/sdk/cli/user.md +++ b/docs/sdk/cli/user.md @@ -108,8 +108,8 @@ tailor-sdk user [command] | ------------------------------- | ------------------------------ | | [`user current`](#user-current) | Show current user. | | [`user list`](#user-list) | List all users. | -| [`user pat`](#user-pat) | Manage personal access tokens. | | [`user switch`](#user-switch) | Set current user. | +| [`user pat`](#user-pat) | Manage personal access tokens. | @@ -243,9 +243,9 @@ tailor-sdk user pat [command] | Command | Description | | ------------------------------------- | ----------------------------------------------------- | +| [`user pat list`](#user-pat-list) | List all personal access tokens. | | [`user pat create`](#user-pat-create) | Create a new personal access token. | | [`user pat delete`](#user-pat-delete) | Delete a personal access token. | -| [`user pat list`](#user-pat-list) | List all personal access tokens. | | [`user pat update`](#user-pat-update) | Update a personal access token (delete and recreate). | diff --git a/docs/sdk/generator/builtin.md b/docs/sdk/generator/builtin.md index a2d8846..fb818c3 100644 --- a/docs/sdk/generator/builtin.md +++ b/docs/sdk/generator/builtin.md @@ -22,7 +22,7 @@ Generates a TypeScript file containing: - Type definitions for all TailorDB types - `getDB(namespace)` function to create Kysely instances -- Utility types for Timestamp and Serial fields +- Utility types for `Timestamp`, `Serial`, and `ObjectColumnType` (wraps nested objects containing date/datetime fields to provide correct insert vs select types) ### Usage diff --git a/docs/sdk/services/auth.md b/docs/sdk/services/auth.md index 19cac71..28678f7 100644 --- a/docs/sdk/services/auth.md +++ b/docs/sdk/services/auth.md @@ -10,6 +10,7 @@ Auth provides: - Machine users for service-to-service authentication - OAuth 2.0 client configuration - Identity provider integration +- Auth connections for external OAuth2 provider integration For the official Tailor Platform documentation, see [Auth Guide](/guides/auth/overview). @@ -47,6 +48,15 @@ const auth = defineAuth("my-auth", { grantTypes: ["authorization_code", "refresh_token"], }, }, + connections: { + "google-connection": { + type: "oauth2", + providerUrl: "https://accounts.google.com", + issuerUrl: "https://accounts.google.com", + clientId: process.env.GOOGLE_CLIENT_ID!, + clientSecret: process.env.GOOGLE_CLIENT_SECRET!, + }, + }, idProvider: idp.provider("my-provider", "my-client"), }); @@ -341,6 +351,106 @@ idProvider: idp.provider("my-provider", "my-client"), See [IdP](idp) for configuring identity providers. +## Auth Connections + +Auth connections enable OAuth2 authentication with external providers (Google, Microsoft 365, QuickBooks, etc.) for application-to-application flows. Functions can access connection tokens at runtime via `tailor.authconnection.getConnectionToken()`. + +For the official Tailor Platform documentation, see [AuthConnection Guide](/guides/auth/authconnection). + +### Setup Flow + +Setting up an auth connection requires two steps: + +1. **Create** the connection (registers the OAuth2 provider credentials) +2. **Authorize** the connection (runs the OAuth2 flow to obtain and store tokens) + +Both steps are needed regardless of whether you manage connections via config or CLI. + +### Configuration + +Define connections in `defineAuth()`: + +```typescript +import { defineAuth } from "@tailor-platform/sdk"; + +export const auth = defineAuth("my-auth", { + // ... other auth config + connections: { + "google-connection": { + type: "oauth2", + providerUrl: "https://accounts.google.com", + issuerUrl: "https://accounts.google.com", + clientId: process.env.GOOGLE_CLIENT_ID!, + clientSecret: process.env.GOOGLE_CLIENT_SECRET!, + }, + }, +}); +``` + +After `tailor-sdk apply`, authorize the connection: + +```bash +tailor-sdk authconnection authorize --name google-connection \ + --scopes "openid,profile,email" +``` + +The authorize command opens a browser for the OAuth2 flow. The authorization code is sent to the platform, which exchanges it for tokens using the client secret registered in the connection config. + +### Connection Config Fields + +| Field | Type | Required | Description | +| -------------- | -------- | -------- | ------------------------------------------- | +| `type` | `string` | Yes | Connection type. Currently only `"oauth2"`. | +| `providerUrl` | `string` | Yes | OAuth2 provider URL. | +| `issuerUrl` | `string` | Yes | OAuth2 issuer URL for JWT validation. | +| `clientId` | `string` | Yes | OAuth2 client ID. | +| `clientSecret` | `string` | Yes | OAuth2 client secret. | +| `authUrl` | `string` | No | Override for the authorization endpoint. | +| `tokenUrl` | `string` | No | Override for the token endpoint. | + +### Change Detection + +The SDK uses hash-based change detection for connection configs. Only connections whose configuration has changed since the last `apply` are updated (revoked and recreated). Deleting the `.tailor-sdk/` directory forces all connections to be re-sent. + +### `auth.getConnectionToken()` + +`auth.getConnectionToken()` retrieves connection tokens at runtime by calling `tailor.authconnection.getConnectionToken()` internally. When `connections` is defined in `defineAuth()`, the connection name is type-checked and autocompleted against the defined keys: + +```typescript +import { auth } from "../tailor.config"; + +// In a resolver, executor, or workflow: +const tokens = await auth.getConnectionToken("google-connection"); +const response = await fetch("https://www.googleapis.com/...", { + headers: { Authorization: `Bearer ${tokens.access_token}` }, +}); + +// auth.getConnectionToken("unknown"); // Type error — only "google-connection" is allowed +``` + +When `connections` is not defined, `getConnectionToken()` accepts any string. This supports connections managed entirely via the CLI. + +See [Built-in Interfaces](/guides/function/builtin-interfaces.html#auth-connection) for the full runtime API. + +### CLI Management + +Auth connections can also be managed via the CLI: + +```bash +# Authorize (opens browser for OAuth2 flow) +tailor-sdk authconnection authorize --name google-connection + +# List all connections +tailor-sdk authconnection list + +# Revoke a connection +tailor-sdk authconnection revoke --name google-connection +``` + +Connection creation is handled by `tailor-sdk apply` via the config. + +See [Auth Resource Commands](../cli/auth) for full CLI documentation. + ## Before Login Hook Run custom logic before a user logs in. This is useful for JIT (Just-In-Time) user provisioning — automatically creating or updating user records when a user authenticates for the first time. @@ -379,6 +489,11 @@ export const auth = defineAuth("my-auth", { Manage Auth resources using the CLI: ```bash +# Auth connections +tailor-sdk authconnection authorize --name +tailor-sdk authconnection list +tailor-sdk authconnection revoke --name + # List machine users tailor-sdk machineuser list diff --git a/docs/sdk/services/idp.md b/docs/sdk/services/idp.md index f2afd76..8dd8539 100644 --- a/docs/sdk/services/idp.md +++ b/docs/sdk/services/idp.md @@ -79,12 +79,12 @@ defineIdp("my-idp", { ### emailConfig -Optional email configuration defaults for emails sent by the IdP (e.g., password reset emails). Per-request values take priority over namespace defaults. +Namespace-level email configuration defaults. Per-request values take priority over these defaults. ```typescript defineIdp("my-idp", { authorization: "loggedIn", - clients: ["default-client"], + clients: ["my-client"], emailConfig: { fromName: "My App", passwordResetSubject: "Reset your password", @@ -94,8 +94,10 @@ defineIdp("my-idp", { **Fields:** -- `fromName` (string, optional) — Default sender display name for emails (e.g., `My App `). Max 200 characters. When omitted, falls back to `"Tailor Platform IdP"`. -- `passwordResetSubject` (string, optional) — Default subject line for password reset emails. Max 200 characters. When omitted, falls back to the localized default subject. +- `fromName` - Default sender display name for emails. Empty means use mailer default. +- `passwordResetSubject` - Default subject for password reset emails. Empty means use localized default. + +**Validation:** Each field must be 200 characters or less and must not contain newline characters. ## Using idp.provider() diff --git a/docs/sdk/services/resolver.md b/docs/sdk/services/resolver.md index d08c11b..cdc4c36 100644 --- a/docs/sdk/services/resolver.md +++ b/docs/sdk/services/resolver.md @@ -13,7 +13,7 @@ Resolvers provide: ## Comparison with Tailor Platform Pipeline Resolver -The SDK's Resolver is a simplified version of Tailor Platform's [Pipeline Resolver](/guides/resolver). +The SDK's Resolver is a simplified version of Tailor Platform's [Pipeline Resolver](/guides/pipeline). | Pipeline Resolver | SDK Resolver | | ---------------------------------------- | --------------------------------- | diff --git a/docs/sdk/services/workflow.md b/docs/sdk/services/workflow.md index 683d0b6..35a2dec 100644 --- a/docs/sdk/services/workflow.md +++ b/docs/sdk/services/workflow.md @@ -12,7 +12,7 @@ Workflows provide: - Access to TailorDB via Kysely query builder - Job triggering to compose multi-step logic -For the official Tailor Platform documentation, see [Workflow Guide](/guides/workflow/). +For the official Tailor Platform documentation, see [Workflow Guide](/guides/workflow). ## Workflow Rules