Project setup

The SDK does not create projects, databases, buckets, or access policies. Set those up in Carpo first, then initialize the client with the identifiers from the project dashboard.

Collect the client settingsCopy Anchor Link

Every client needs the Carpo API origin and a project ID. The Database Data API and Storage client also need the ID of the managed database or bucket they will use.

const config = {
  apiUrl: 'https://api.carpo.dev',
  projectId: 'your-project-id',
  databaseId: 'your-database-id',
  environment: 'production' as const,
}

apiUrl must be the API origin only. Do not add /api, a path, query string, or fragment. environment is production or development and defaults to production.

Project IDs, database IDs, bucket IDs, and the API origin identify resources. They are not credentials. Database access tokens and project API keys are credentials and must remain on trusted servers.

Enable Database Data API accessCopy Anchor Link

Database reads and writes from browser and request scoped clients use the Database Data API. For each database and environment:

1. Open the project's database settings in Carpo.
2. Enable the Data API for the target environment.
3. Add each exposed table and grant only the required read, insert, update, and delete operations.
4. Choose an all row scope or an owner column scope for each table.

The API is disabled by default and table access is denied until an owner or admin configures it. Production and Development permissions are independent. With an owner column scope, Carpo sets the column from the authenticated Project Auth user. The client cannot override that owner value.

Browser writes that use the Project Auth cookie also require the app's exact origin in the trusted origins for that Project Auth environment. Keep the environment used by the client aligned with the Project Auth instance and Data API policy you configured.

Configure Project AuthCopy Anchor Link

The React client uses Project Auth session cookies by default. Configure the sign in methods for the environment and add the browser application's exact origin to its trusted origins. The client plugin list lets TypeScript call Carpo supported Better Auth features, but a client plugin does not enable a feature on the Project Auth server.

For bearer authentication, use a Project Auth JWT or a user scoped Project Auth API key. The browser SDK accepts a token getter. Do not use a project server API key as a browser bearer token.

Configure StorageCopy Anchor Link

Before a Storage client can access a bucket, wait for the bucket to become ready and configure the bucket's access policies in Carpo. Policies are denied by default. Public policies allow reads and listings only. Authenticated writes also require a trusted app origin when they use a session cookie.

Browser transfers go directly between the browser and R2 using short lived signed URLs. Add each app origin to the bucket's R2 CORS configuration and allow the request methods and headers used by the signed transfer. The Storage SDK does not edit bucket settings or policies.

Configure Function accessCopy Anchor Link

Function invocation access, CORS, and limits are attached to each deployed version. Configure the deployment's invocation mode in Carpo. The SDK forwards the Project Auth credentials it has, but the deployed Function remains responsible for accepting or rejecting the request.