TrueRecord SDK for TypeScript

TrueRecord keeps a record of every interaction with an AI system in your app. This SDK sends those records. Each message is encrypted before it leaves your process, so only TrueRecord can process it. See the TrueRecord SDK docs for setup and guides.

Works in Node 18+, browsers, Deno and Bun. No runtime dependencies.

Install

npm install truerecord-sdk

Quick start

import { TrueRecordClient, TrueRecordError } from "truerecord-sdk";

const client = new TrueRecordClient({
  apiKey: "tr_sk_...",
  applicationGuid: "...",
  interactionGuid: "...",
});

try {
  // Send the message your user sends to the LLM
  await client.send({ message: userMessage, origin: "user" });

  // Send a message from the LLM to the user
  await client.send({ message: llmMessage, origin: "llm" });
} catch (e) {
  if (e instanceof TrueRecordError) console.error(e.message);
}

The client fetches your application's public key from TrueRecord the first time it sends, and again if TrueRecord has replaced it. You don't need to download or configure it.

Where the public key is kept

By default the client keeps the key in memory, so a process fetches it once. That suits servers, workers and anything else that sends more than once.

A process that only lives for a send or two, such as a hook script or a CLI command, would fetch the key on every run. On Node, turn on fileCache so every run shares one copy on disk:

const client = new TrueRecordClient({
  apiKey: "tr_sk_...",
  applicationGuid: "...",
  interactionGuid: "...",
  fileCache: true,
  // cachePath: "/var/cache/myapp/truerecord.key", // optional, must be absolute
});

| Option | Default | Description | |---|---|---| | fileCache | false | Keep the key in a file instead of in memory. Node only. | | cachePath | <user cache dir>/truerecord/<applicationGuid>.key | The file. Only with fileCache: true. ~ is expanded; the path must be absolute. The user cache dir is %LOCALAPPDATA% on Windows, ~/Library/Caches on macOS and $XDG_CACHE_HOME or ~/.cache elsewhere. |

The file holds only the public key, which is not a secret. If it can't be read or written, the client fetches the key instead; it never fails a send.

To check your API key and guids at setup without sending anything, call await client.refreshPublicKey(). It throws AuthenticationError if any of them is wrong.

What to send

Each call to send creates a record of one message, either what the user sent ("user") or what the LLM sent ("llm"). Use the same conversationRef for both so TrueRecord can pair them.

client.send({ message, origin, messageDatetime?, conversationRef?, hook? });

| Argument | Required | Description | |---|---|---| | message | Yes | The message a user sent to the AI or the AI sent to the user. Can be any value that converts to JSON (string, object, array, etc.). | | origin | Yes | "user" if this is a message sent to the LLM, "llm" if it's the LLM's response. Other values are allowed but not supported. | | messageDatetime | No | When the message happened, as an ISO 8601 string (e.g. "2025-01-15T10:30:00Z"). When not set defaults to the current time. | | conversationRef | No | A reference you choose (like a session ID or chat ID) to link related messages together. Pass the same value for a user message and its AI response so TrueRecord can pair them. | | hook | No | A hook name, as a string. |

Implementation details

Non-blocking (recommended)

Sending data to TrueRecord runs in the background so the rest of your code continues without waiting for TrueRecord to respond.

Skip the await and attach a .catch() instead. Always attach .catch(). Without it, a failure becomes an unhandled promise rejection, which crashes Node.

client
  .send({ message: userMessage, origin: "user" })
  .catch((e) => console.error(e.message));

client
  .send({ message: llmMessage, origin: "llm" })
  .catch((e) => console.error(e.message));

Blocking

Sending data to TrueRecord waits for TrueRecord to respond before the rest of your code continues.

await client.send({ message: userMessage, origin: "user" });
await client.send({ message: llmMessage, origin: "llm" });

Errors

All errors extend TrueRecordError, so you can catch them in one place.

| Error | When | |---|---| | ValidationError | A required argument is missing or the message can't be serialised to JSON. | | EncryptionError | The public key TrueRecord returned isn't a valid RSA key. | | NetworkError | TrueRecord couldn't be reached after retries. | | AuthenticationError | The API key, or the guids it was used with, were rejected. | | PublicKeyRejectedError | TrueRecord rejected the public key even after the client fetched it again. A kind of APIError. | | APIError | Any other server error. Has statusCode and detail. |

License

MIT