@tidblink/server 0.0.0-stage → 0.3.0-rc.0

package/examples/provision-user.mjs

@@ -0,0 +1,83 @@
+import { open } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import {
+  ConflictError,
+  OrganizationClient,
+  OutcomeUnknownError,
+} from "@tidblink/server";
+
+/** Each successful invocation issues a new credential. Retain it in your secret manager. */
+export async function provisionUser({
+  baseUrl,
+  organizationApiKey,
+  externalId,
+  displayName,
+}) {
+  const client = new OrganizationClient({
+    baseUrl,
+    apiKey: organizationApiKey,
+  });
+  const organization = await client.getOrganization();
+  const mapping = externalId.trim();
+  if (!mapping)
+    throw new TypeError("externalId is required for reconciliation");
+  const find = async () =>
+    (await client.listEndUsers()).find((user) => user.externalId === mapping);
+  let user = await find();
+  if (!user) {
+    try {
+      user = await client.createEndUser({
+        externalId: mapping,
+        ...(displayName === undefined ? {} : { displayName }),
+      });
+    } catch (error) {
+      if (
+        !(error instanceof OutcomeUnknownError) &&
+        !(error instanceof ConflictError && error.code === "resource_conflict")
+      )
+        throw error;
+      user = await find().catch(() => undefined);
+      if (!user) throw error;
+    }
+  }
+  // Metadata cannot recover a lost token. This issuance is deliberately never repeated here.
+  const issued = await client.createUserApiKey(user.userId, {
+    name: "application-backend",
+  });
+  return { organization, user, ...issued };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  const {
+    AGENT_SERVICE_URL,
+    ORGANIZATION_API_KEY,
+    END_USER_EXTERNAL_ID,
+    USER_CREDENTIAL_FILE,
+  } = process.env;
+  if (
+    !AGENT_SERVICE_URL ||
+    !ORGANIZATION_API_KEY ||
+    !END_USER_EXTERNAL_ID ||
+    !USER_CREDENTIAL_FILE
+  ) {
+    throw new Error(
+      "Set AGENT_SERVICE_URL, ORGANIZATION_API_KEY, END_USER_EXTERNAL_ID and USER_CREDENTIAL_FILE",
+    );
+  }
+  // Reserve a new private destination before issuing a credential; never overwrite an existing secret.
+  const destination = await open(USER_CREDENTIAL_FILE, "wx", 0o600);
+  try {
+    const result = await provisionUser({
+      baseUrl: AGENT_SERVICE_URL,
+      organizationApiKey: ORGANIZATION_API_KEY,
+      externalId: END_USER_EXTERNAL_ID,
+    });
+    await destination.writeFile(JSON.stringify(result) + "\n");
+    console.log("User credential saved to USER_CREDENTIAL_FILE");
+  } finally {
+    await destination.close();
+  }
+}

package/examples/read-usage.mjs

@@ -0,0 +1,62 @@
+import { pathToFileURL } from "node:url";
+import { UserClient, OrganizationClient } from "@tidblink/server";
+
+export async function readOwnUsage({ baseUrl, userApiKey, options = {} }) {
+  const user = new UserClient({ baseUrl, apiKey: userApiKey });
+  return {
+    summary: await user.getUsage(options),
+    details: await user.getUsageDetails(options),
+  };
+}
+
+/** Organization details return the first page; retain nextCursor and the original filters. */
+export async function readUserUsage({
+  baseUrl,
+  organizationApiKey,
+  userId,
+  options,
+}) {
+  const organization = new OrganizationClient({
+    baseUrl,
+    apiKey: organizationApiKey,
+  });
+  const { interval, ...range } = options;
+  return {
+    summary: await organization.getUserUsage(userId, options),
+    details: await organization.getUserUsageDetails(userId, range),
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const options = {
+      from: process.env.USAGE_FROM,
+      to: process.env.USAGE_TO,
+      tagKey: process.env.TAG_KEY,
+      tagValue: process.env.TAG_VALUE,
+    };
+    const baseUrl = process.env.AGENT_SERVICE_URL;
+    let result;
+    if (process.env.USAGE_AUTHORITY === "user")
+      result = await readOwnUsage({
+        baseUrl,
+        userApiKey: process.env.USER_API_KEY,
+        options,
+      });
+    else if (process.env.USAGE_AUTHORITY === "organization")
+      result = await readUserUsage({
+        baseUrl,
+        organizationApiKey: process.env.ORGANIZATION_API_KEY,
+        userId: process.env.END_USER_ID,
+        options,
+      });
+    else throw new TypeError("USAGE_AUTHORITY must be user or organization");
+    console.log(JSON.stringify(result));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : "Usage read failed");
+    process.exitCode = 1;
+  }
+}

package/examples/schedule-task.mjs

@@ -0,0 +1,67 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { pathToFileURL } from "node:url";
+import { UserClient } from "@tidblink/server";
+
+/** Persist the exact runAt, prompt and creation key before calling. */
+export async function scheduleTaskWorkflow({
+  baseUrl,
+  userApiKey,
+  agentId,
+  idempotencyKey,
+  runAt,
+  prompt,
+  title = "Scheduled task",
+  timeoutMs = 30000,
+}) {
+  const user = new UserClient({ baseUrl, apiKey: userApiKey });
+  const created = await user.schedulers.create({
+    agentId,
+    idempotencyKey,
+    title,
+    prompt,
+    schedule: { kind: "once", runAt },
+  });
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const { fires } = await user.schedulers.fires(
+      created.scheduler.schedulerId,
+    );
+    const fire = fires.find((item) => item.executionStatus !== "pending");
+    if (fire) {
+      const turn =
+        fire.result.sessionId && fire.result.turnId
+          ? await user
+              .session(fire.result.sessionId)
+              .getTurn(fire.result.turnId)
+          : null;
+      return { scheduler: created.scheduler, fire, turn };
+    }
+    await delay(100);
+  }
+  throw new Error(
+    `Waiting stopped; read Scheduler ${created.scheduler.schedulerId} fires later. Its schedule remains active.`,
+  );
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const result = await scheduleTaskWorkflow({
+      baseUrl: process.env.AGENT_SERVICE_URL,
+      userApiKey: process.env.USER_API_KEY,
+      agentId: process.env.AGENT_ID,
+      idempotencyKey: process.env.SCHEDULER_IDEMPOTENCY_KEY,
+      runAt: process.env.SCHEDULE_RUN_AT,
+      prompt: process.env.SCHEDULE_PROMPT,
+    });
+    console.log(JSON.stringify(result));
+    if (result.fire.executionStatus === "failed") process.exitCode = 1;
+  } catch (error) {
+    console.error(
+      error instanceof Error ? error.message : "Scheduled task failed",
+    );
+    process.exitCode = 1;
+  }
+}

package/examples/send-message.mjs

@@ -0,0 +1,43 @@
+import { pathToFileURL } from "node:url";
+import { UserClient } from "@tidblink/server";
+
+/** Persist sessionId, clientEventId and text before calling; reuse them for recovery. */
+export async function sendMessageWorkflow({
+  baseUrl,
+  userApiKey,
+  sessionId,
+  clientEventId,
+  text,
+  timeoutMs,
+  signal,
+}) {
+  const session = new UserClient({ baseUrl, apiKey: userApiKey }).session(
+    sessionId,
+  );
+  return session.turn(
+    { clientEventId, text, ...(signal ? { signal } : {}) },
+    {
+      ...(timeoutMs === undefined ? {} : { timeoutMs }),
+      ...(signal ? { signal } : {}),
+    },
+  );
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const result = await sendMessageWorkflow({
+      baseUrl: process.env.AGENT_SERVICE_URL,
+      userApiKey: process.env.USER_API_KEY,
+      sessionId: process.env.SESSION_ID,
+      clientEventId: process.env.CLIENT_EVENT_ID,
+      text: process.env.MESSAGE_TEXT,
+    });
+    console.log(result.text);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : "Message failed");
+    process.exitCode = 1;
+  }
+}

package/examples/submit-audio.mjs

@@ -0,0 +1,52 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { pathToFileURL } from "node:url";
+import { UserClient } from "@tidblink/server";
+
+/** This recording request owns its response; aborting it may interrupt the Turn. */
+export async function submitAudioWorkflow({
+  baseUrl,
+  userApiKey,
+  sessionId,
+  bytes,
+  filename,
+  contentType,
+  billingTag,
+  signal,
+}) {
+  return new UserClient({ baseUrl, apiKey: userApiKey })
+    .session(sessionId)
+    .audio({
+      bytes,
+      filename,
+      ...(contentType === undefined ? {} : { contentType }),
+      ...(billingTag === undefined ? {} : { billingTag }),
+      ...(signal ? { signal } : {}),
+    });
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    if (!process.env.AUDIO_FILE_PATH)
+      throw new Error("Set AUDIO_FILE_PATH to an existing recording");
+    const result = await submitAudioWorkflow({
+      baseUrl: process.env.AGENT_SERVICE_URL,
+      userApiKey: process.env.USER_API_KEY,
+      sessionId: process.env.SESSION_ID,
+      filename: basename(process.env.AUDIO_FILE_PATH),
+      bytes: await readFile(process.env.AUDIO_FILE_PATH),
+      contentType: process.env.AUDIO_CONTENT_TYPE,
+    });
+    console.log(result.text);
+  } catch (error) {
+    console.error(
+      error instanceof Error ? error.message : "Audio request failed",
+    );
+    if (typeof error?.turnId === "string")
+      console.error(`Turn: ${error.turnId}`);
+    process.exitCode = 1;
+  }
+}

package/examples/upload-file.mjs

@@ -0,0 +1,53 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { pathToFileURL } from "node:url";
+import { UserClient } from "@tidblink/server";
+
+/** Persist both identities and exact file/message input before calling. */
+export async function uploadFileWorkflow({
+  baseUrl,
+  userApiKey,
+  sessionId,
+  originalName,
+  bytes,
+  idempotencyKey,
+  clientEventId,
+  text = "Read the attached file.",
+  timeoutMs,
+}) {
+  const user = new UserClient({ baseUrl, apiKey: userApiKey });
+  const file = await user.files.upload({ originalName, bytes, idempotencyKey });
+  const result = await user
+    .session(sessionId)
+    .turn(
+      { clientEventId, text, userFileIds: [file.fileId] },
+      { ...(timeoutMs === undefined ? {} : { timeoutMs }) },
+    );
+  return { file, result };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    if (!process.env.FILE_PATH)
+      throw new Error("Set FILE_PATH to the file to attach");
+    const { result } = await uploadFileWorkflow({
+      baseUrl: process.env.AGENT_SERVICE_URL,
+      userApiKey: process.env.USER_API_KEY,
+      sessionId: process.env.SESSION_ID,
+      originalName: basename(process.env.FILE_PATH),
+      bytes: await readFile(process.env.FILE_PATH),
+      idempotencyKey: process.env.UPLOAD_IDEMPOTENCY_KEY,
+      clientEventId: process.env.CLIENT_EVENT_ID,
+      text: process.env.MESSAGE_TEXT,
+    });
+    console.log(result.text);
+  } catch (error) {
+    console.error(
+      error instanceof Error ? error.message : "File workflow failed",
+    );
+    process.exitCode = 1;
+  }
+}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@tidblink/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0-rc.0",
+  "description": "Official TypeScript SDK for TiDB Link",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "tidbLinkApiVersion": "0.0.1",
+  "tidbLinkRevision": "882287809f91d9a3fdf60537460431d9f0fc23e7",
+  "tidbLinkOpenApiSha256": "906515e4c8d38c5ac9fce6390d9d646220b2d06100fbcb64e180419899989a5b",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./examples/provision-user.mjs": "./examples/provision-user.mjs",
+    "./examples/prepare-realtime-connection.mjs": "./examples/prepare-realtime-connection.mjs",
+    "./examples/create-session.mjs": "./examples/create-session.mjs",
+    "./examples/send-message.mjs": "./examples/send-message.mjs",
+    "./examples/control-turn.mjs": "./examples/control-turn.mjs",
+    "./examples/observe-message.mjs": "./examples/observe-message.mjs",
+    "./examples/read-usage.mjs": "./examples/read-usage.mjs",
+    "./examples/upload-file.mjs": "./examples/upload-file.mjs",
+    "./examples/schedule-task.mjs": "./examples/schedule-task.mjs",
+    "./examples/answer-client-tool.mjs": "./examples/answer-client-tool.mjs",
+    "./examples/submit-audio.mjs": "./examples/submit-audio.mjs",
+    "./examples/organization-session.mjs": "./examples/organization-session.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "examples/provision-user.mjs",
+    "examples/prepare-realtime-connection.mjs",
+    "examples/create-session.mjs",
+    "examples/send-message.mjs",
+    "examples/control-turn.mjs",
+    "examples/observe-message.mjs",
+    "examples/read-usage.mjs",
+    "examples/upload-file.mjs",
+    "examples/schedule-task.mjs",
+    "examples/answer-client-tool.mjs",
+    "examples/submit-audio.mjs",
+    "examples/organization-session.mjs"
+  ],
+  "scripts": {
+    "build": "node --eval \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "typecheck": "npm run build",
+    "test": "npm run build && node --test 'test/**/*.test.mjs'",
+    "test:service-contract": "node --test 'service-contract/**/*.test.mjs'",
+    "pack:check": "npm pack --dry-run",
+    "test:service": "npm run build && node test/service/run.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mem9-ai/tidblink-sdk.git",
+    "directory": "typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/mem9-ai/tidblink-sdk/issues"
+  },
+  "homepage": "https://github.com/mem9-ai/tidblink-sdk#readme"
+}