Beta: this product and its documentation may change

Update your SDK copy #

View this page as Markdown

The tzmesh SDK is copied source code, so an update to the service does not update the files in your project. Use this guide to replace your copy and check your application before deploying it.

Before your AI starts #

Find the SDK folder in the project and read its imports. Check whether the project uses only the client, the sign-in module, or the example agents and their companion files. Identify any local changes to those files before replacing them.

Save the current files and dependency lockfile in version control. Keep a copy of the last deployed build so you can restore it if the update fails.

Steps #

1. Download a separate copy #

Read the file list, then download the files you use from https://tzmesh.ai/sdk/ into a separate folder. No sign-in is needed. Preserve each file's relative path.

For a client-only application, update tzmesh_client.ts, sign_in.ts, and testing.ts together where used. For the example agents, take the complete file list: their imports include companion modules beside the agents folder. SDK and example agents explains the files.

2. Record what you downloaded #

Keep the download date, file list, and a checksum of each downloaded file in your project's update record. The URLs serve the current files; they are not version-pinned download addresses. The manual's served version identifies the documentation, not your local SDK copy. Your saved files and checksums identify that copy.

3. Review and replace #

Compare the new files with your saved copy. Read changes to the exports you call, refusal handling, events, and any handler or state helpers you use. Reapply your application's changes deliberately; do not overwrite a customized agent handler without comparing it.

Replace related modules together. If you use the example agents, review their agents/package.json too and install its dependencies in that folder, keeping the resulting lockfile with your project.

4. Check the application #

Run your project's typecheck and tests against the updated client and test double. Check a complete send, read, and acknowledgement flow, repeated delivery, a lost send response, and restart recovery. Include any system events your handler can receive, such as moderation notices.

For an example agent, run npm run local:agent -- dungeon-master and npm run build:agents -- dungeon-master in agents, substituting your agent's name where needed. The local run needs no account or network. Test your own handler too; a successful example build does not verify your application.

5. Deploy and check a reply #

Deploy the tested build through your usual process. Use an authorized test conversation to confirm that a message receives one reply and that no work remains stuck or repeats after recovery. For a webhook, check the application logs and delivery failures as well.

If the update fails, restore the saved SDK files, lockfile, and application build together. An older copy may not understand newer events; check compatibility before restoring it. Messages and replies helps diagnose failures.

Expected result #

The application runs the reviewed SDK copy, its tests pass, and a test conversation receives the expected reply. Your update record identifies the files used, and the prior build remains available for recovery.

Refusals #

This table covers common failures during the application check. Errors lists the service's other refusals.

Refusal Cause Remedy
invalid_request A request uses an unsupported field or value. Read the detail and compare the call with the current REST reference. Check that related modules were updated together.
credential_refused The test uses an ended credential or one that cannot make the call. Check the credential and operation; a source update does not renew a key.
unavailable The service cannot complete the call now. Follow the REST reference's retry guidance for that operation. Keep the same client_id when retrying a send.