Working with extension data and integrations

Connect your extension to durable data and external services through its server backend. Cedros provides separate contracts for records, settings, encrypted secrets, files, provider calls, and scheduled work. Choosing the right one makes setup, permissions, and recovery easier to manage.

This guide assumes you have followed Building your first extension and have a test site that supports your Wasm backend. Use the target host's supported interface and capabilities; a manifest declaration requests access but does not configure a provider or authorize every caller.

Choose where each value belongs

For an extension that synchronizes orders with another service, separate its data like this:

• Order records: extension-owned content models accessed through the host database interface.
• Sync preferences: extension settings, such as whether synchronization is enabled.
• A token for the downstream service: encrypted extension secret storage, when the service is not already provided by Cedros.
• Export files or attachments: the host storage provider, with metadata and ownership recorded in your data model.
• Recurring sync times: Cedros automation schedules.
• Run results: durable outcome records and redacted diagnostic logs.

Browser state is suitable for a form's unsaved edits. Persist shared settings and records through your server routes so they survive refreshes and work across devices. Keep credentials out of browser bundles, manifests, ZIPs, logs, and job metadata.

Declare and protect your records

1. Declare your content model IDs in surfaces.server.contentModels[]. Prefix each ID with your extension ID, for example acme-orders:orders.
2. Add a databaseAccess[] entry with its own namespaced ID, a clear description, the declared model references, and only the operations the feature needs.
3. Implement server routes or jobs that use that access ID with the host database interface. Have your UI call those routes.
4. Validate the caller, input, and ownership before accessing a record. Test both a permitted request and one targeting another user's data.

Cedros provisions declared content models as host-managed JSONB collections during installation. Reads, counts, writes, and deletes are checked against the access entry's models and scopes. The scope's resource description helps an owner review the request; it does not add a row-level ownership check. Your extension must enforce which records a caller may access.

Use stable record keys and paginate reads. For changes that depend on an expected record version, use the documented compare-and-set contract and declare its required capability. An ordinary read followed by a write can overwrite a concurrent edit; handle a conflict by reloading and resolving the change.

Use the site database reference for payloads, scopes, conditional writes, and migration limits. Extensions receive scoped database operations, not a database connection or arbitrary SQL access. Plan richer schema changes with the host and document how updates preserve existing records.

Save settings and secrets separately

Declare surfaces.server.settingsSchemas[] for extension configuration. The server's settings interface provides get, set, and list-all for extension JSON values. Use stable, namespaced keys and validate values before saving them.

Each settings.set call saves one key. If several independent fields change together, track which saves succeeded and leave failed fields unsaved. If the values must change together, use the documented conditional configuration operation instead of treating sequential calls as a transaction.

Use the server's secrets interface for extension-specific credentials. Reads and writes require the host's encrypted-secret storage to be configured. Show a useful setup error if it is unavailable; never fall back to a plain setting. If you retain a secret reference, treat it as an opaque handle and keep the actual value on the server.

Let an authorized owner replace or remove a credential without exposing its existing value. Read back safe configuration state after saving, and make the UI distinguish a configured credential from a successful connection test.

The settings and secrets reference covers persistence, atomic configuration changes, rotation, and upgrade behavior.

Call the site's configured providers

Declare each provider use in providerAccess[], then call providers.execute from your server backend using the matching access ID, provider, and operation. Cedros checks the grant and routes the request through the site's configured service.

• Files: use the storage provider's put, get, and delete operations. Keys are isolated to your extension. Keep each file's ownership and purpose in your records, and check access before returning private content.
• Email: use the email provider's send operation. The site's configured sender and delivery limits apply. A missing email configuration produces an error; there is no fallback sender.
• AI features: use the documented intelligence provider contract and the site's permitted models. Make the cost-bearing action clear to the user before running it. A readiness check is not a guarantee that a later request will succeed.

Provider credentials and shared provider setup belong to Cedros. Your extension can offer feature preferences, such as when to send a notification, without collecting a second copy of the site's email or AI key.

Handle provider errors explicitly. For missing configuration, direct the owner to the relevant provider settings. For an outage or timeout, retain the pending work and explain what can be retried. Before retrying an action that sends or creates something, determine whether the first attempt completed; a lost response does not prove that it failed.

The host provider reference defines supported payloads, operation scopes, limits, and error codes. A stored file key is not automatically a public download URL; provide an appropriate server route when your feature needs to serve private files.

Schedule work through Cedros

Declare job IDs in surfaces.server.jobs[] and implement the matching list-jobs and run-job exports in your Wasm component. The declaration and executable handler must agree.

Runtime schedules live in Cedros automation settings. You can offer manual scheduling or declare jobSchedules[] with autoCreateOnEnable: true to provision a default schedule when the extension is enabled. Automatic provisioning preserves an existing owner-configured schedule.

Choose a cadence and timezone, keep each run bounded, and save progress when a sync needs several runs. Job metadata should contain safe inputs, not credentials or trusted permission claims.

Return succeeded, failed, or retryable according to the result. Cedros can retry a retryable outcome when the schedule allows retries; retries are bounded and use backoff. Make each unit of work idempotent so repeating it does not duplicate an order, notification, or other external effect. Record enough redacted context for an owner to understand and recover a failed run.

Use the jobs and scheduling reference for the execution contract. Document missed runs, disabling, re-enabling, and data retention as part of your extension's setup instructions.

Verify access and recovery on a test site

Before releasing the integration:

1. Save a record and a setting, reload the interface, and confirm the values persist. Exercise a conflicting update and check that it cannot silently overwrite newer data.
2. Test unauthenticated requests, missing permissions, and attempts to access another user's records. Reject invalid input before performing a write or provider call.
3. Test missing credentials and unavailable providers. Verify that errors expose no secrets and that the UI does not report an uncommitted change as saved.
4. Run a job with synthetic data, then repeat its work and exercise a retryable failure. Confirm the result in the destination system and check that external effects are not duplicated.
5. Disable and re-enable the extension, then test an update from the previous version. Confirm the expected schedules, settings, secrets, and records are preserved or removed according to your documented policy.

For admin routes, check the host-supplied admin identity and permission claims, and enforce the host's CSRF requirements for writes. Public customer sessions have a separate authentication contract: an admin-session flag is not proof of a customer's identity. See the server backend reference for the exact context and route contracts.

Keep the tested package, configuration requirements, and recovery steps with the release. A successful provider response or job dispatch is only one part of verification; also check the saved state and the outcome your user expects.