The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Update doc (#26204)
martmull3e016b12307e
diff --git a/packages/twenty-docs/developers/extend/apps/logic/credits.mdx b/packages/twenty-docs/developers/extend/apps/logic/credits.mdxindex 51daa89fc1a..5dab47b705d 100644--- a/packages/twenty-docs/developers/extend/apps/logic/credits.mdx+++ b/packages/twenty-docs/developers/extend/apps/logic/credits.mdx@@ -65,7 +65,7 @@ billing: {| Field | Description ||-------|-------------|| `period` | `MONTH` — the only period today |-| `amountMicroCredits` | Amount in micro-credits (1 USD = 1,000,000), a positive integer up to 100,000,000 ($100). For a `WORKSPACE_MEMBER` charge this is the rate **per member**, not the total |+| `amountMicroCredits` | Amount in micro-credits (1 USD = 1,000,000), a positive integer up to 100,000,000 (\$100). For a `WORKSPACE_MEMBER` charge this is the rate **per member**, not the total || `per` | Omit for a flat fee. `WORKSPACE_MEMBER` multiplies the amount by the number of members in the workspace when the period is charged || `label` | What admins read for that line in Usage |@@ -75,7 +75,7 @@ How they are raised:- Not prorated. An app installed mid-period is charged the full amount for that period; uninstalling stops the next period, it does not refund the current one.- Per-member charges count all workspace members at the moment the charge is raised, so a workspace that grows mid-period pays the higher count from the next period.- Only on monthly subscriptions. A workspace on a yearly plan is not charged a `MONTH` fee, rather than being charged once for the whole year.-- Bounded. A declared rate above $100, or a per-member charge whose rate multiplied by the member count would exceed $1,000 for the period, is refused and not raised. The platform raises these itself, so it will not write a debit it cannot justify.+- Bounded. A declared rate above \$100, or a per-member charge whose rate multiplied by the member count would exceed \$1,000 for the period, is refused and not raised. The platform raises these itself, so it will not write a debit it cannot justify.## Billable operationsdiff --git a/packages/twenty-docs/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/developers/extend/apps/logic/logic-functions.mdxindex ccff5dbbf2b..ad1b5c73d0e 100644--- a/packages/twenty-docs/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/developers/extend/apps/logic/logic-functions.mdx@@ -309,7 +309,7 @@ const handler = async (event: RoutePayload) => {`httpMethods` replaces the default rather than adding to it, so `['GET']` alone makes the route reject `POST`. Only `GET` and `POST` are supported. Leave it unset unless the provider needs the second verb: a route that declares `GET` will have its resolver executed by any unauthenticated caller, including the crawlers and link unfurlers that send `GET` unprompted. Anything the platform does not have a method for is answered `405` without the resolver ever running.<Note>-**The application must be claimed and installed on its owner workspace.** Because the resolver runs in the **owner workspace** (the workspace that owns the application registration), a server route trigger only works once the application has been *claimed* — i.e. it has an owner workspace — **and** that application is **installed on the owner workspace**. Until both are true the resolver has nowhere to run, so the route cannot be dispatched. An application that exposes a `serverRouteTriggerSettings` logic function therefore cannot be listed in the marketplace until it is claimed and installed on its owner workspace.+**The application must be claimed and installed on its owner workspace.** Follow [Claiming your app](/developers/extend/apps/operations/publishing#claiming-your-app) to assign an owner, then install the app in that workspace. Until both are true, the resolver has nowhere to run and the server route returns `404` (`LOGIC_FUNCTION_NOT_FOUND`), even if the app is installed elsewhere. Marketplace search hides apps with server routes until this setup and all required server variables are complete. See [owner workspace costs and availability](/developers/extend/apps/operations/publishing#owner-workspace-costs-and-availability) for billing and operational details.</Note>**Resolver contract.** The SDK's `LogicFunctionConfig` type enforces this at compile time: as soon as you set `serverRouteTriggerSettings`, your handler is constrained to return either a `Response`, or `{ workspaceId: string; targetLogicFunctionUniversalIdentifier: string; payload?: object }` (or a `Promise` of either). On the dispatch path, the `workspaceId` must be a workspace where the target function is installed, otherwise the request is rejected with `404`. A result that matches neither shape — including one whose identifiers are not UUIDs — is rejected with `502`.diff --git a/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/developers/extend/apps/operations/publishing.mdxindex 306dbd55f29..e2f6778b236 100644--- a/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx+++ b/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx@@ -9,7 +9,7 @@ description: Distribute your Twenty app to the marketplace or deploy it internalOnce your app is [built and tested locally](/developers/extend/apps/getting-started/concepts), you have two paths for distributing it:- **Deploy a tarball** — upload your app directly to a specific Twenty server for internal or private use.-- **Publish to npm** — list your app in the Twenty marketplace for any workspace to discover and install.+- **Publish to npm** — publish your package, [claim it in Twenty](#claiming-your-app), and complete its setup so other workspaces can discover and install it.Both paths start from the same **build** step.@@ -29,7 +29,7 @@ Syncing code and a manifest under an identifier is a claim of authorship, so beiTwo situations lead to that refusal:- **The identifier belongs to another workspace.** Change the `universalIdentifier` in your app config, which is the usual answer when you forked someone else's app. If you need to keep the identifier, the owning workspace has to transfer the registration to yours.-- **The identifier belongs to no workspace.** Apps imported by the marketplace catalog sync start unowned. Claim yours through npm trusted publishing before developing on it.+- **The identifier belongs to no workspace.** Apps imported by the marketplace catalog sync start unowned. [Claim yours with GitHub](#claiming-your-app) before developing on it. Publishing with npm provenance provides proof of authorship; it does not automatically assign an owner workspace in Twenty.## Building your app@@ -182,7 +182,7 @@ Publishes your app to npm with provenance when you push a version tag (e.g. `v1.**One-time setup:**-On npmjs.com open your package > **Settings → Trusted Publisher** and register this repository with the `publish.yml` workflow (see the [npm trusted publishing docs](https://docs.npmjs.com/trusted-publishers)). Publishing with provenance certifies which GitHub repository built the package, which is also how you claim ownership of your app in a Twenty marketplace.+On npmjs.com open your package > **Settings → Trusted Publisher** and register this repository with the `publish.yml` workflow (see the [npm trusted publishing docs](https://docs.npmjs.com/trusted-publishers)). Publishing with provenance certifies which GitHub repository built the package. After publishing, [claim ownership in Twenty](#claiming-your-app).<Note>npm only accepts provenance from **public** source repositories. If you publish from a private repo, npm rejects the OIDC provenance bundle with an `E422 ... Unsupported GitHub Actions source repository visibility: "private"` error. To publish from a private repo, opt out of provenance by setting `TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'` in the publish step's `env` (a commented-out hint is included in the scaffolded `publish.yml`):@@ -193,6 +193,8 @@ npm only accepts provenance from **public** source repositories. If you publishTWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'run: yarn twenty app:publish```++Without GitHub provenance, the package cannot be claimed through **Claim with GitHub**. Use a public repository with provenance if you need this ownership flow.</Note>### Pinning the reusable actions@@ -201,7 +203,7 @@ The `ci.yml` and `cd.yml` workflows reference reusable actions at `@main`, so ac## Publishing to npm-Publishing to npm makes your app discoverable in the Twenty marketplace. Any Twenty workspace can browse, install, and upgrade marketplace apps directly from the UI.+Publishing to npm makes your app eligible for the Twenty marketplace. After catalog sync and any required [server-route setup](#setting-up-server-routes), workspaces can browse, install, and upgrade it from the UI. Community apps appear when users turn off the **Vetted only** filter.### Requirements@@ -289,6 +291,69 @@ For other CI systems (GitLab CI, CircleCI, etc.), run `yarn install` then `yarn**npm provenance** adds a trust badge to your npm listing, letting users verify the package was built from a specific commit in a public CI pipeline. It is also what lets you claim ownership of your app in a Twenty marketplace. See the [npm provenance docs](https://docs.npmjs.com/generating-provenance-statements) for details.</Note>+After the package has synced into the catalog, continue with [Claiming your app](#claiming-your-app). The claim flow requires provenance pointing to a **GitHub** repository.++## Claiming your app++Claiming assigns your app's registration to the Twenty workspace that will manage it. App claiming is available to all workspaces. Your role needs the **Applications** and **MCP & APIs** permissions to claim through the **Developer** tab.++Ownership is per Twenty instance: claiming on Twenty Cloud does not claim the app on a separate self-hosted server. Other workspaces on the same instance install your app without claiming it themselves.++### Before you claim++- Publish your package from a **public GitHub repository** using GitHub Actions and [npm trusted publishing with provenance](#ci-publishing). The version imported into Twenty's catalog must carry the provenance attestation.+- Include the `twenty-app` keyword in `package.json` and wait for [catalog sync](#how-marketplace-discovery-works).+- Choose the workspace that will own the app. For apps with server routes, this workspace also runs and pays for the shared resolver.+- Sign in to GitHub as the **personal account that owns the source repository**, or as an **owner of the organization** that owns it. Repository collaborator access or npm package maintainer access alone is not sufficient.++### Claim with GitHub++1. In your intended owner workspace, go to **Settings > Applications > Developer** (`/settings/applications#developer`).+2. In **Claim an application**, enter the exact npm package name, including its scope (for example, `@your-org/twenty-app`), or the app's `universalIdentifier`.+3. Click **Look up** and check that the result is your app. If it is not found, click **Sync catalog** if available, wait for the sync to finish, then look it up again.+4. Click **Claim with GitHub** and authorize Twenty. For an organization-owned repository, grant access to that organization in GitHub's **Organization access** section. Personal repositories do not need an organization grant.+5. When you return to Twenty, confirm that the app appears under **My apps** with type **NPM**. Open it and check **Distribution > Ownership** for **Claimed by this workspace**.++Claiming does not install the app. If it exposes server routes, complete the setup below before other workspaces depend on its webhooks.++### Setting up server routes++A [server route](/developers/extend/apps/logic/logic-functions#server-route-trigger) receives events for multiple workspaces at one URL. Its resolver runs in the registration's **owner workspace**, then dispatches work to the appropriate installed workspace.++1. Open your app under **My apps** and fill in any required **Server Variables** in the **Config** tab.+2. In **Distribution**, click **See on marketplace** to open the app page and install it in the **owner workspace**. You can open this page even before the app appears in marketplace search.+3. Register the server webhook URL with your provider and test an event from a second workspace where the app is installed. Check both the resolver and the target function's logs.++<Warning>+An unclaimed app, or an app not installed in its owner workspace, has no server-route resolver to run. Requests return `404` (`LOGIC_FUNCTION_NOT_FOUND`), even if the app is installed in other workspaces. These apps stay out of marketplace search until claimed, installed on the owner workspace, and configured with all required server variables.+</Warning>++### Owner workspace costs and availability++See [how logic function runs are metered](/user-guide/billing/capabilities/credits#how-logic-function-runs-are-metered) for credit consumption, pricing, and which workspace is billed.++Uninstalling the app from the owner workspace or deleting that workspace removes the shared resolver and interrupts server webhooks for every install on that instance.++### Ownership after a repository move++Moving the GitHub repository to another personal account or organization does not transfer or remove an existing Twenty claim. The registration remains attached to its owner workspace. Keep the same npm package and app `universalIdentifier`; changing the Twenty owner workspace requires a separate ownership transfer.++### Troubleshooting a claim++If you have trouble claiming your app, contact us on [Discord](https://discord.gg/cx5n4Jzs57) or [open a GitHub issue](https://github.com/twentyhq/twenty/issues/new/choose).++<Accordion title="Self-hosted GitHub claim configuration">+The server administrator configures `APP_CLAIM_GITHUB_CLIENT_ID` and `APP_CLAIM_GITHUB_CLIENT_SECRET` with a GitHub OAuth app. Set its authorization callback URL to your `SERVER_URL` followed by `/application-registration-claim/github/callback`, for example `https://twenty.example.com/application-registration-claim/github/callback`. This configuration is already managed for you on Twenty Cloud.+</Accordion>++## Marketplace visibility and vetting++Claiming establishes ownership; it does not grant a **Vetted** badge. The marketplace defaults to **Vetted only**. To find community apps, go to **Settings > Applications > Marketplace**, open the filter, and uncheck **Vetted only**. You can also share your app's direct install page using **My apps > your app > Distribution > Copy sharing link**.++The Vetted label currently applies to apps maintained by Twenty, for which the team can vouch for security and quality. Third-party apps can be published and installed without this label.++If your app is still missing with **Vetted only** turned off, confirm catalog sync has completed, all required server variables are filled in, and any server-route setup is complete.+## Installing appsOnce an app is published (npm) or deployed (tarball), workspaces can install it through the UI.diff --git a/packages/twenty-docs/user-guide/billing/capabilities/credits.mdx b/packages/twenty-docs/user-guide/billing/capabilities/credits.mdxindex 0d152128c1d..7844e58d278 100644--- a/packages/twenty-docs/user-guide/billing/capabilities/credits.mdx+++ b/packages/twenty-docs/user-guide/billing/capabilities/credits.mdx@@ -7,7 +7,7 @@ description: One simple balance that powers your workflows, AI agents, and AI chCredits are a single balance that powers everything we run on your behalf that has a real cost: **workflow automations**, **AI agents**, and the **AI chat**. Instead of juggling separate quotas for "automation runs" and "AI tokens," you have one simple balance to keep an eye on.-**1 credit = $1 of usage.** A credit is just a dollar of work, so your balance is easy to reason about — no abstract units to convert.+**1 credit = \$1 of usage.** A credit is just a dollar of work, so your balance is easy to reason about — no abstract units to convert.## How far does a credit go?@@ -15,11 +15,11 @@ Cost scales with the work. Everyday automation and quick AI messages cost a tiny| What you do | Roughly costs | What that means ||-------------|---------------|-----------------|-| Run a standard workflow step (search, create, or update records) | $0.0001 | **10,000 runs per credit** |-| Trigger an app's logic function | $0.0001 + $0.0001 per second of runtime | **Thousands of runs per credit** |+| Run a standard workflow step (search, create, or update records) | \$0.0001 | **10,000 runs per credit** |+| Trigger an app's logic function | \$0.0001 + \$0.0001 per second of runtime | **Thousands of runs per credit** || Call an external API or run a code node | A small fraction of a credit | Thousands per credit || Send a quick AI chat message or simple AI step | A fraction of a cent | Hundreds per credit |-| Run a large AI agent task (e.g. "configure 10 workspace objects") | Can run to **~$1 or more** | A few per credit |+| Run a large AI agent task (e.g. "configure 10 workspace objects") | Can run to **~\$1 or more** | A few per credit || Run an AI web search | A fixed per-search cost | Hundreds of searches per credit |<Note>@@ -34,10 +34,12 @@ Not every app charges for its runs. Call Recorder, Last Contact, Fathom and GranLogic function pricing mirrors AWS Lambda: a flat charge per invocation plus a duration charge for the time your code actually runs, billed per millisecond.-- **Per invocation**: $0.0001-- **Per duration**: $0.0001 per second of runtime ($0.0000001 per millisecond)+- **Per invocation**: \$0.0001+- **Per duration**: \$0.0001 per second of runtime (\$0.0000001 per millisecond)-A typical function that finishes in under a second costs at most double the flat invocation charge. Long-running functions pay for the compute they use: a function running for a full minute adds $0.006, and one hitting the 15-minute timeout adds $0.09. A function that times out is billed for its full elapsed time, just like on AWS.+A typical function that finishes in under a second costs at most double the flat invocation charge. Long-running functions pay for the compute they use: a function running for a full minute adds \$0.006, and one hitting the 15-minute timeout adds \$0.09. A function that times out is billed for its full elapsed time, just like on AWS.++For apps with [server routes](/developers/extend/apps/operations/publishing#owner-workspace-costs-and-availability), the resolver runs against the app owner's workspace balance. A target function dispatched to another workspace is billed separately to that workspace.## How AI usage is metered@@ -51,8 +53,8 @@ Every subscription includes credits, and the amount depends on your **billing cy| Billing Cycle | Included Credits | Equivalent Usage ||---------------|------------------|------------------|-| Monthly | 5 / month | ~$5 of usage each month |-| Yearly | 50 / year | ~$50 of usage each year |+| Monthly | 5 / month | ~\$5 of usage each month |+| Yearly | 50 / year | ~\$50 of usage each year |These credits are designed to cover everyday automation comfortably. Five credits cover tens of thousands of standard automation steps or hundreds of quick AI messages — though a handful of large, multi-step agent tasks can use them up faster. You can top up at any time (see below).