@characterxyz/server 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charky Labs Pvt Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @characterxyz/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Character XYZ on your server. Mint a session for a signed-in visitor with your secret key, and verify
+webhook signatures. Works in Node 18+, Deno, Bun and edge runtimes.
+
+```ts
+import { createSession, verifyWebhook } from '@characterxyz/server';
+
+const session = await createSession({
+  secretKey: process.env.CHARACTERXYZ_SECRET_KEY!,
+  visitor: { id: user.id },
+  origin: 'https://www.example.com',
+});
+```
+
+A secret key never belongs in a browser: `createSession` refuses to run in one.
+
+See the [repository README](https://github.com/characterxyz/characterxyz-sdk#readme) for usage, security and customising.

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import { SessionInfo } from '@characterxyz/web';
+export { SessionInfo } from '@characterxyz/web';
+
+/**
+ * `@characterxyz/server` — mint a session for a SIGNED-IN visitor, on
+ * your server, with your secret key; verify webhooks. Node 18+, Deno, Bun,
+ * edge runtimes. Zero dependencies at runtime.
+ *
+ * ```ts
+ * // e.g. a Next.js route handler: GET /api/characterxyz/session
+ * import { createSession } from '@characterxyz/server';
+ *
+ * export async function GET() {
+ *   const user = await currentUser();
+ *   const session = await createSession({
+ *     secretKey: process.env.CHARACTERXYZ_SECRET_KEY!,
+ *     visitor: { id: user.id },
+ *     origin: 'https://www.example.com',
+ *   });
+ *   return Response.json(session);
+ * }
+ * ```
+ *
+ * Then in the page: `CharacterXYZ.init({ getSessionToken: () => fetch('/api/characterxyz/session').then(r => r.json()) })`.
+ * The visitor's chat history then follows them across devices, and webhooks
+ * carry your id for them as `externalId`.
+ */
+
+interface CreateSessionOptions {
+    /** `cxyz_sk_…` — from your server's environment, never from code. */
+    secretKey: string;
+    /** Your id for this person (≤ 128 characters). Omit for an anonymous visitor. */
+    visitor?: {
+        id: string;
+    };
+    agentId?: string;
+    /** The site the session will be used from; binds it there. Must be on the key. */
+    origin?: string;
+    apiUrl?: string;
+}
+declare function createSession(opts: CreateSessionOptions): Promise<SessionInfo>;
+/**
+ * Check a webhook's `Cxyz-Signature` header. Pass the RAW body string, exactly
+ * as received. Rejects anything older than `toleranceSeconds` (default 300).
+ */
+declare function verifyWebhook(opts: {
+    secret: string;
+    body: string;
+    signature: string | null;
+    toleranceSeconds?: number;
+    now?: number;
+}): Promise<boolean>;
+
+export { type CreateSessionOptions, createSession, verifyWebhook };

package/dist/index.js

@@ -0,0 +1,3 @@
+async function g(e){if(typeof window<"u"&&typeof document<"u")throw new Error("createSession runs on your server. A secret key must never reach a browser.");let s=(e.apiUrl??"https://api.character.xyz").replace(/\/+$/,""),r=await fetch(`${s}/sdk/v1/sessions`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${e.secretKey}`},body:JSON.stringify({agentId:e.agentId,visitor:e.visitor,origin:e.origin})}),n=await r.json().catch(()=>({}));if(!r.ok||!n.data)throw new Error(`Character XYZ session failed (${r.status}): ${n.message??"unknown error"}`);return n.data}async function l(e){let s=e.signature??"",r=Object.fromEntries(s.split(",").map(t=>t.split("=",2))),n=Number(r.t),o=r.v1;if(!n||!o)return  false;let c=e.now??Math.floor(Date.now()/1e3);if(Math.abs(c-n)>(e.toleranceSeconds??300))return  false;let d=await crypto.subtle.importKey("raw",new TextEncoder().encode(e.secret),{name:"HMAC",hash:"SHA-256"},false,["sign"]),f=new Uint8Array(await crypto.subtle.sign("HMAC",d,new TextEncoder().encode(`${n}.${e.body}`))),i=Array.from(f,t=>t.toString(16).padStart(2,"0")).join("");if(i.length!==o.length)return  false;let a=0;for(let t=0;t<i.length;t++)a|=i.charCodeAt(t)^o.charCodeAt(t);return a===0}
+export{g as createSession,l as verifyWebhook};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["createSession","opts","apiUrl","res","body","verifyWebhook","sig","parts","p","t","v1","now","key","mac","expected","b","diff","i"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * `@characterxyz/server` — mint a session for a SIGNED-IN visitor, on\n * your server, with your secret key; verify webhooks. Node 18+, Deno, Bun,\n * edge runtimes. Zero dependencies at runtime.\n *\n * ```ts\n * // e.g. a Next.js route handler: GET /api/characterxyz/session\n * import { createSession } from '@characterxyz/server';\n *\n * export async function GET() {\n *   const user = await currentUser();\n *   const session = await createSession({\n *     secretKey: process.env.CHARACTERXYZ_SECRET_KEY!,\n *     visitor: { id: user.id },\n *     origin: 'https://www.example.com',\n *   });\n *   return Response.json(session);\n * }\n * ```\n *\n * Then in the page: `CharacterXYZ.init({ getSessionToken: () => fetch('/api/characterxyz/session').then(r => r.json()) })`.\n * The visitor's chat history then follows them across devices, and webhooks\n * carry your id for them as `externalId`.\n */\nimport type { SessionInfo } from '@characterxyz/web';\n\nexport interface CreateSessionOptions {\n  /** `cxyz_sk_…` — from your server's environment, never from code. */\n  secretKey: string;\n  /** Your id for this person (≤ 128 characters). Omit for an anonymous visitor. */\n  visitor?: { id: string };\n  agentId?: string;\n  /** The site the session will be used from; binds it there. Must be on the key. */\n  origin?: string;\n  apiUrl?: string;\n}\n\nexport async function createSession(opts: CreateSessionOptions): Promise<SessionInfo> {\n  if (typeof window !== 'undefined' && typeof document !== 'undefined') {\n    throw new Error('createSession runs on your server. A secret key must never reach a browser.');\n  }\n  const apiUrl = (opts.apiUrl ?? 'https://api.character.xyz').replace(/\\/+$/, '');\n  const res = await fetch(`${apiUrl}/sdk/v1/sessions`, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${opts.secretKey}` },\n    body: JSON.stringify({ agentId: opts.agentId, visitor: opts.visitor, origin: opts.origin }),\n  });\n  const body = (await res.json().catch(() => ({}))) as { data?: SessionInfo; message?: string };\n  if (!res.ok || !body.data) throw new Error(`Character XYZ session failed (${res.status}): ${body.message ?? 'unknown error'}`);\n  return body.data;\n}\n\n/**\n * Check a webhook's `Cxyz-Signature` header. Pass the RAW body string, exactly\n * as received. Rejects anything older than `toleranceSeconds` (default 300).\n */\nexport async function verifyWebhook(opts: { secret: string; body: string; signature: string | null; toleranceSeconds?: number; now?: number }): Promise<boolean> {\n  const sig = opts.signature ?? '';\n  const parts = Object.fromEntries(sig.split(',').map((p) => p.split('=', 2) as [string, string]));\n  const t = Number(parts.t);\n  const v1 = parts.v1;\n  if (!t || !v1) return false;\n  const now = opts.now ?? Math.floor(Date.now() / 1000);\n  if (Math.abs(now - t) > (opts.toleranceSeconds ?? 300)) return false;\n  const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(opts.secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);\n  const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${t}.${opts.body}`)));\n  const expected = Array.from(mac, (b) => b.toString(16).padStart(2, '0')).join('');\n  if (expected.length !== v1.length) return false;\n  let diff = 0;\n  for (let i = 0; i < expected.length; i++) diff |= expected.charCodeAt(i) ^ v1.charCodeAt(i);\n  return diff === 0;\n}\n\nexport type { SessionInfo };\n"]}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@characterxyz/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Character XYZ on your server: mint a session for a signed-in visitor with your secret key, and verify webhook signatures. Node, Deno, Bun and edge runtimes.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@characterxyz/web": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/characterxyz/characterxyz-sdk.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://character.xyz",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }