{"_id":"@cardochat/sdk","_rev":"3-0f2de6c6e78310a748134f57db13223a","name":"@cardochat/sdk","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@cardochat/sdk","version":"1.0.0","keywords":["chat","messaging","realtime","socket.io","react","cardochat","cardochat-sdk"],"license":"MIT","_id":"@cardochat/sdk@1.0.0","maintainers":[{"name":"cardoverli","email":"cardoverli03@gmail.com"}],"homepage":"https://github.com/cardoverli-FU/cardochat/tree/main/packages/sdk#readme","bugs":{"url":"https://github.com/cardoverli-FU/cardochat/issues"},"dist":{"shasum":"4b5302344a7c481cdaa0167020dab9e9aff9b908","tarball":"https://registry.npmjs.org/@cardochat/sdk/-/sdk-1.0.0.tgz","fileCount":47,"integrity":"sha512-TLaJO/Lh6ccAAiUCmjUAEGiXOYhHe3TaNZn+VhztbSEfiDda4bhQ+jZQz8gECG3+ZHm3HQttQrA/PyxwtOB8Pg==","signatures":[{"sig":"MEUCIQC8ipfIGBue/nq8Su1NhYRaBBAcOKue1dAnEmwRytZvrQIgKvI1Qnz6ixzD/jWhquUxkNpviM6at4Y8s4MJ+Pys3HM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":159862},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.js"}},"gitHead":"9ed2ad9d7eea8e253fb371a56e26137c99ed10ab","scripts":{"lint":"tsc --noEmit","build":"tsc && bash scripts/post-build.sh","prepack":"npm run build","prepublishOnly":"npm run build"},"_npmUser":{"name":"cardoverli","email":"cardoverli03@gmail.com"},"repository":{"url":"git+https://github.com/cardoverli-FU/cardochat.git","type":"git","directory":"packages/sdk"},"_npmVersion":"11.16.0","description":"Official Cardochat SDK — multi-tenant chat API client + React components","directories":{},"_nodeVersion":"24.18.0","dependencies":{"socket.io-client":"^4.8.3"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5","@types/react":"^19"},"peerDependencies":{"react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"peerDependenciesMeta":{"react":{"optional":true},"react-dom":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_1.0.0_1786113224546_0.48623104991638","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@cardochat/sdk","version":"1.0.1","keywords":["chat","messaging","realtime","socket.io","react","cardochat","cardochat-sdk"],"license":"MIT","_id":"@cardochat/sdk@1.0.1","maintainers":[{"name":"cardoverli","email":"cardoverli03@gmail.com"}],"homepage":"https://github.com/cardoverli-FU/cardochat/tree/main/packages/sdk#readme","bugs":{"url":"https://github.com/cardoverli-FU/cardochat/issues"},"dist":{"shasum":"aa4a1f4130e091529807d65cdb49daab58372c6f","tarball":"https://registry.npmjs.org/@cardochat/sdk/-/sdk-1.0.1.tgz","fileCount":47,"integrity":"sha512-/9N8rM+ETiN0mr5qFxx4zwOEMOEPwbc2sYeFNw1FYoBF/M3Ub2MX3FAaNYEjarvdy78ggJHMq3oIr9grxRSPeA==","signatures":[{"sig":"MEUCIEFqFUo+rkDht44VNVr5P0ldAEaBLUL6FmAR86YhD5iUAiEAloKnLmK38zaB5kctNEsyy0vSa2e0DBCuvXoNt0B78/o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":159862},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.js"}},"gitHead":"9ed2ad9d7eea8e253fb371a56e26137c99ed10ab","scripts":{"lint":"tsc --noEmit","build":"tsc && bash scripts/post-build.sh","prepack":"npm run build","prepublishOnly":"npm run build"},"_npmUser":{"name":"cardoverli","email":"cardoverli03@gmail.com"},"repository":{"url":"git+https://github.com/cardoverli-FU/cardochat.git","type":"git","directory":"packages/sdk"},"_npmVersion":"11.16.0","description":"Official Cardochat SDK — multi-tenant chat API client + React components","directories":{},"_nodeVersion":"24.18.0","dependencies":{"socket.io-client":"^4.8.3"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5","@types/react":"^19"},"peerDependencies":{"react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"peerDependenciesMeta":{"react":{"optional":true},"react-dom":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_1.0.1_1786113402548_0.9873089246106768","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@cardochat/sdk","version":"1.0.2","description":"Official Cardochat SDK — multi-tenant chat API client + React components","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.js"}},"scripts":{"build":"tsc && bash scripts/post-build.sh","lint":"tsc --noEmit","prepublishOnly":"npm run build","prepack":"npm run build"},"dependencies":{"socket.io-client":"^4.8.3"},"peerDependencies":{"react":"^18.0.0 || ^19.0.0","react-dom":"^18.0.0 || ^19.0.0"},"peerDependenciesMeta":{"react":{"optional":true},"react-dom":{"optional":true}},"devDependencies":{"@types/node":"^26.2.0","@types/react":"^19","typescript":"^5"},"keywords":["chat","messaging","realtime","socket.io","react","cardochat","cardochat-sdk"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/cardoverli-FU/cardochat.git","directory":"packages/sdk"},"homepage":"https://github.com/cardoverli-FU/cardochat/tree/main/packages/sdk#readme","bugs":{"url":"https://github.com/cardoverli-FU/cardochat/issues"},"engines":{"node":">=18.0.0"},"gitHead":"ac60c8cfd549512639fa6389d04bfc5190177ee8","_id":"@cardochat/sdk@1.0.2","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-Uj0AftSWAc8LCRP2ABWpxf8fTuApZFJAYcGS7z/wMwVzgQjrbe2JkvtiuCj/jRsU0JwCdFGHmuT+alQ3KsfBSA==","shasum":"32e8f64652fcc760666630cd71ba6054f4fd62c0","tarball":"https://registry.npmjs.org/@cardochat/sdk/-/sdk-1.0.2.tgz","fileCount":47,"unpackedSize":166327,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDNAE1pqdDVaU+qwuy9ZgzRpFSZJDRxLDkBM1e0q1r9UQIgLKmpof3pKz/uh8Sh6FC0hNmYDWAyRUAYREJIBh4oSzM="}]},"_npmUser":{"name":"cardoverli","email":"cardoverli03@gmail.com"},"directories":{},"maintainers":[{"name":"cardoverli","email":"cardoverli03@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.0.2_1786850601532_0.18593123995899608"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-07T14:33:44.375Z","modified":"2026-08-16T03:23:21.895Z","1.0.0":"2026-08-07T14:33:44.694Z","1.0.1":"2026-08-07T14:36:42.712Z","1.0.2":"2026-08-16T03:23:21.723Z"},"bugs":{"url":"https://github.com/cardoverli-FU/cardochat/issues"},"license":"MIT","homepage":"https://github.com/cardoverli-FU/cardochat/tree/main/packages/sdk#readme","keywords":["chat","messaging","realtime","socket.io","react","cardochat","cardochat-sdk"],"repository":{"type":"git","url":"git+https://github.com/cardoverli-FU/cardochat.git","directory":"packages/sdk"},"description":"Official Cardochat SDK — multi-tenant chat API client + React components","maintainers":[{"name":"cardoverli","email":"cardoverli03@gmail.com"}],"readme":"# @cardochat/sdk\n\n> Official **Cardochat** SDK — multi-tenant chat API client + React components.\n\nAdd real-time chat to any web app in under 5 minutes. REST API + Socket.IO + React UI + push notifications, all in one tree-shakeable TypeScript package.\n\n## Install\n\n```bash\nnpm install @cardochat/sdk socket.io-client\n# or\nbun add @cardochat/sdk socket.io-client\n# or\nyarn add @cardochat/sdk socket.io-client\n```\n\n## Quick Start (3 steps, <5 min)\n\n### 1. Get your API keys\n\nFrom your Cardochat dashboard, register an app and copy:\n- **Public key** (`pk_...`) — safe for browser\n- **Private key** (`sk_...`) — server-side only\n\n### 2. Create a client (server-side, for REST)\n\n```ts\nimport { CardochatClient } from \"@cardochat/sdk\"\n\nconst client = new CardochatClient({\n  appId: \"your-app-id\",\n  privateKey: \"sk_...\",\n  publicKey: \"pk_...\",\n  baseUrl: \"https://your-engine-url.com\",\n})\n\n// Create a conversation\nconst conv = await client.createConversation({\n  type: \"direct\",\n  members: [\"alice\", \"bob\"],\n})\n\n// Send a message\nawait client.sendMessage(conv.id, {\n  userId: \"alice\",\n  content: \"Hello from Cardochat!\",\n})\n```\n\n### 3. Drop in the chat UI (browser, React)\n\n```tsx\nimport { ChatWindow, useCardochatSocket, useConversation } from \"@cardochat/sdk/react\"\n\nfunction App() {\n  const socket = useCardochatSocket({\n    appId: \"your-app-id\",\n    publicKey: \"pk_...\",\n    userToken: async () => {\n      // Call your backend to get a JWT for this user\n      const res = await fetch(\"/api/token\")\n      return res.json().then(r => r.token)\n    },\n    url: \"https://your-engine-url.com\",\n  })\n\n  return (\n    <ChatWindow\n      socket={socket}\n      conversationId=\"conv_...\"\n      userId=\"alice\"\n      theme={{\n        colors: { primary: \"#10b981\", background: \"#ffffff\" },\n      }}\n    />\n  )\n}\n```\n\nThat's it — you have a working chat with typing indicators, read receipts, presence, and auto-reconnect.\n\n## 📚 Documentation\n\n| What you need | Where to find it |\n|---------------|------------------|\n| **5-min quickstart** | [docs/GETTING_STARTED.md](https://github.com/cardoverli-FU/cardochat/blob/main/docs/GETTING_STARTED.md) |\n| **Full integration tutorial** (step-by-step, all features) | [docs/APP_INTEGRATION.md](https://github.com/cardoverli-FU/cardochat/blob/main/docs/APP_INTEGRATION.md) |\n| **API reference** (every endpoint + SDK method) | [docs/API_CONTRACT.md](https://github.com/cardoverli-FU/cardochat/blob/main/docs/API_CONTRACT.md) |\n| **Webhook events** (signatures + payloads) | [docs/WEBHOOKS.md](https://github.com/cardoverli-FU/cardochat/blob/main/docs/WEBHOOKS.md) |\n| **Database schema** | [docs/DB_SCHEMA.md](https://github.com/cardoverli-FU/cardochat/blob/main/docs/DB_SCHEMA.md) |\n| **Deployment guide** (self-host engine + dashboard) | [docs/DEPLOYMENT.md](https://github.com/cardoverli-FU/cardochat/blob/main/docs/DEPLOYMENT.md) |\n\n**New to Cardochat?** Start with the [5-min quickstart](https://github.com/cardoverli-FU/cardochat/blob/main/docs/GETTING_STARTED.md), then read the [full integration tutorial](https://github.com/cardoverli-FU/cardochat/blob/main/docs/APP_INTEGRATION.md) for webhooks, push notifications, and theming.\n\n## What's Included\n\n### Core (no React required)\n\n| Export | Description |\n|--------|-------------|\n| `CardochatClient` | REST API client — 20+ typed methods for apps, conversations, messages, presence, push, moderation |\n| `CardochatSocket` | Socket.IO client — real-time events, auto-reconnect, token refresh |\n| `CardochatError` | Typed error with `code`, `status`, `retryAfter`, `retryable`, `isAuthError` |\n| `verifyWebhookSignature` | HMAC-SHA256 webhook verification (timing-safe) |\n| `subscribeToPush` | Browser Web Push subscription (VAPID + service worker) |\n| `registerCapacitorPushToken` | Capacitor APK push registration (FCM/APNS) |\n| `fetchVapidPublicKey` | Fetch VAPID public key from engine |\n\n### React Components & Hooks\n\n| Export | Description |\n|--------|-------------|\n| `<ChatWindow>` | Full chat UI — messages, input, typing, presence. Drop-in. |\n| `<MessageList>` | Paginated message list with auto-scroll |\n| `<MessageBubble>` | Individual message bubble (mine/theirs/system/deleted) |\n| `<MessageInput>` | Input with Enter-to-send, typing indicator |\n| `<TypingIndicator>` | Animated typing dots |\n| `<ConversationList>` | Sidebar conversation list |\n| `useCardochatSocket` | Hook — manages socket lifecycle + connection state |\n| `useConversation` | Hook — messages, typing, presence, read receipts, pagination |\n| `themeToCssVars` | Convert theme object to CSS custom properties |\n| `defaultTheme` / `lightTheme` | Pre-built themes |\n\n## REST API Methods\n\n```ts\nconst client = new CardochatClient({ appId, privateKey, publicKey, baseUrl })\n\n// Apps\nclient.getApp(appId)\nclient.updateApp(appId, { name, webhookUrl, ... })\nclient.rotateKeys(appId)\n\n// Conversations\nclient.createConversation({ type, members, name })\nclient.listConversations({ limit, cursor })\nclient.getConversation(id)\nclient.updateConversation(id, { name })\nclient.deleteConversation(id)\nclient.addMembers(id, userIds)\nclient.removeMember(id, userId)\n\n// Messages\nclient.sendMessage(conversationId, { userId, content, type })\nclient.listMessages(conversationId, { limit, cursor })\nclient.editMessage(messageId, { content })\nclient.deleteMessage(messageId)\nclient.markAsRead(messageId, userId)\n\n// Presence\nclient.getPresence(userId)\n\n// Push subscriptions\nclient.registerPushSubscription(userId, { endpoint, keys, provider })\nclient.listPushSubscriptions(userId)\nclient.unregisterPushSubscription(userId, endpoint)\n\n// Moderation\nclient.listModerationEvents({ limit, cursor, appId })\n\n// Webhooks\nclient.verifyWebhookSignature(rawBody, signature, signingSecret)\n```\n\n## Socket.IO Events\n\n```ts\nconst socket = new CardochatSocket({ appId, publicKey, userToken, url })\n\n// Connect\nsocket.connect()\nsocket.disconnect()\nsocket.onConnectionStateChange((state) => {})\n\n// Real-time events\nsocket.onMessage((msg) => {})\nsocket.onMessageUpdated((msg) => {})\nsocket.onMessageDeleted((msg) => {})\nsocket.onTyping((data) => {})\nsocket.onPresence((data) => {})\nsocket.onReadReceipt((data) => {})\nsocket.onConversationUpdated((conv) => {})\n\n// Actions\nsocket.joinConversation(conversationId)\nsocket.leaveConversation(conversationId)\nsocket.sendMessage(conversationId, { userId, content })  // Promise-based\nsocket.editMessage(messageId, { content })\nsocket.deleteMessage(messageId)\nsocket.startTyping(conversationId)\nsocket.stopTyping(conversationId)\nsocket.markRead(messageId)\nsocket.requestPresence(userId)\n```\n\n## Theming\n\n```tsx\n<ChatWindow\n  socket={socket}\n  conversationId={convId}\n  userId=\"alice\"\n  theme={{\n    colors: {\n      primary: \"#10b981\",\n      primaryForeground: \"#ffffff\",\n      background: \"#ffffff\",\n      foreground: \"#0f172a\",\n      muted: \"#f1f5f9\",\n      mine: \"#10b981\",\n      mineForeground: \"#ffffff\",\n      theirs: \"#f1f5f9\",\n      theirsForeground: \"#0f172a\",\n    },\n    fonts: {\n      base: \"Inter, system-ui, sans-serif\",\n      mono: \"ui-monospace, monospace\",\n    },\n    borderRadius: 12,\n    bubble: {\n      maxWidth: 75,\n    },\n  }}\n/>\n```\n\nOr use CSS variables directly:\n\n```css\n[data-cardochat-root] {\n  --cc-primary: #10b981;\n  --cc-background: #ffffff;\n  --cc-mine: #10b981;\n  /* ... */\n}\n```\n\n## Push Notifications\n\n### Web Push (browser)\n\nThe `subscribeToPush` helper handles VAPID key fetch + service worker registration +\nserver registration in one call. Pass your `CardochatClient` instance — it does the\nregistration internally (do NOT call `client.registerPushSubscription` separately,\nor you'll double-register).\n\n```ts\nimport { subscribeToPush } from \"@cardochat/sdk\"\n\nconst { subscriptionId, endpoint } = await subscribeToPush({\n  client,        // your CardochatClient instance\n  userId: \"alice\",\n  // vapidPublicKey is optional — fetched from engine automatically if omitted\n  // swPath is optional — defaults to \"/sw.js\"\n})\n```\n\n### Capacitor (APK)\n\nRequires a `CardochatClient` instance (the helper registers the token server-side).\n\n```ts\nimport { registerCapacitorPushToken } from \"@cardochat/sdk\"\n\n// After Capacitor PushNotifications plugin registers\nawait registerCapacitorPushToken({\n  client,        // your CardochatClient instance\n  userId: \"alice\",\n  token: fcmToken,\n  provider: \"fcm\", // or \"apns\"\n})\n```\n\n## Webhook Verification\n\n```ts\nimport { verifyWebhookSignature } from \"@cardochat/sdk\"\n\nconst isValid = verifyWebhookSignature(\n  rawBody,        // string — the raw request body\n  signature,      // string — from x-cardochat-signature header\n  signingSecret,  // string — your app's signing secret\n)\n```\n\n## TypeScript\n\nFull TypeScript types included. No `@types/*` package needed.\n\n```ts\nimport type {\n  App, Conversation, Message, User,\n  CardochatTheme, ConnectionState,\n  SendMessagePayload, MessageNewPayload,\n} from \"@cardochat/sdk\"\n```\n\n## Environments\n\nThe SDK works in:\n- **Browser** (Chrome, Firefox, Safari, Edge — including mobile)\n- **Node.js** 18+ (for server-side REST calls)\n- **React** 18 / 19 (for `<ChatWindow>` and hooks)\n- **Capacitor** (for APK builds — Web Push falls back to FCM/APNS)\n\n## Architecture\n\n```\nYour App (browser/APK)                    Cardochat Engine (your server)\n┌─────────────────────────┐              ┌──────────────────────────┐\n│  <ChatWindow />         │  HTTP REST   │  REST API                │\n│  CardochatClient        │─────────────▶│  /api/v1/conversations   │\n│  CardochatSocket        │  Socket.IO   │  /api/v1/messages        │\n│  (from @cardochat/sdk)│◀────────────│  Socket.IO server        │\n└─────────────────────────┘              │  Turso DB (LibSQL)       │\n                                         │  Webhooks + Push         │\n                                         └──────────────────────────┘\n```\n\nThe SDK is a **thin client**. All data (conversations, messages, users) lives on your Cardochat engine. The SDK makes authenticated HTTP calls and opens a Socket.IO connection — that's it.\n\n## API Key Security\n\n- **Public key** (`pk_...`) — safe to ship in browser/APK. Scoped to one app. Rate-limited server-side.\n- **Private key** (`sk_...`) — server-side only. Used for admin operations (create conversations, manage members).\n- **Signing secret** — used to verify webhooks. Never expose to browser.\n\n## Links\n\n- [Full Documentation](https://github.com/cardoverli-FU/cardochat/tree/main/docs)\n- [Getting Started Guide](https://github.com/cardoverli-FU/cardochat/blob/main/docs/GETTING_STARTED.md)\n- [API Reference](https://github.com/cardoverli-FU/cardochat/blob/main/docs/API_CONTRACT.md)\n- [GitHub](https://github.com/cardoverli-FU/cardochat)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}