@murmurly/sdk 0.3.0

package/AI_GUIDE.md

@@ -0,0 +1,49 @@
+# AI Coding Agent Integration Guide for @murmurly/sdk
+
+For AI coding assistants (Cursor, Claude Code, GitHub Copilot, ChatGPT, Lovable, Bolt.new) adding Murmurly engagement requests to a project.
+
+---
+
+## 1. Keys: what you may see, and what you must never ask for
+
+- `murmur_id_…` is a **client id**. For a public app it is the whole key and may appear in page source. You may read it and write it into code.
+- `murmur_secret_…` is a **secret key**. **Never ask the user to paste it into the conversation**, and never write it into code, a prompt, a commit, a log or a URL. If the user pastes one anyway, do not repeat it back; tell them to replace it in Murmurly (App settings → Keys & permissions → Replace secret).
+
+To get a secret key into the project, ask the user to run this in their own terminal. It prompts for the key without echoing it, verifies it, writes it to `.env.local` and adds that file to `.gitignore`:
+
+```bash
+npx @murmurly/sdk init
+```
+
+Then read it from the environment: `process.env.MURMURLY_SECRET_KEY`. On a host or in CI, the user sets `MURMURLY_SECRET_KEY` and `MURMURLY_BASE_URL` in the platform's secret store.
+
+## 2. Where the code runs
+
+- **Secret key → server only.** API routes, server actions, workers. Never in a client component, and never behind a `VITE_`, `NEXT_PUBLIC_`, `PUBLIC_` or `REACT_APP_` prefix. The SDK throws if a secret key is used in a browser.
+- **Client id → browser is fine.** The page's origin must be on the app's allowed origins in Murmurly. If the browser gets a `403` about the origin, tell the user to add it there.
+
+## 3. The client
+
+```typescript
+import { createMurmurlyClient } from '@murmurly/sdk'
+
+export const murmurly = createMurmurlyClient({
+  apiKey: process.env.MURMURLY_SECRET_KEY!,
+  baseUrl: process.env.MURMURLY_BASE_URL!
+})
+```
+
+## 4. The flow
+
+1. `await murmurly.eventTypes.list()` returns the types this app was granted: `{ id, name, slug, shortcode, description, color, icon }[]`. An empty list means an admin has not granted any yet.
+2. `await murmurly.eventTypes.getSchema(slug)` returns `{ eventType, sections, jsonSchema }`. `sections[].attributes[]` are the fields (`key`, `label`, `type`, `required`, `config`); send their values under `attributes` using `key`. Send nothing that is not in `jsonSchema`.
+3. `await murmurly.eventTypes.availability({ eventType, from, to })` returns `closedDays`, `earliestOpenDate`, `openHours` and the workspace `timeZone`. Advisory: offer open days first, but a closed day is still accepted.
+4. `await murmurly.engagements.request(payload, { idempotencyKey })` submits. Generate one idempotency key per submission (`crypto.randomUUID()`) and reuse it for that submission's retries.
+5. `await murmurly.engagements.get(idOrShortcode)` reads its status back (confidential apps with `engagements:read_own`).
+
+## 5. Common mistakes
+
+1. **Hand-writing HTTP calls.** Use the SDK: it sends the key, parses errors into `MurmurlyApiError` (with `code` and `retryAfter`) and types the responses.
+2. **Guessing attribute names.** Read them from `getSchema`; unknown fields are refused with `422`.
+3. **Retrying without an idempotency key.** It can create the same request twice.
+4. **Live schema.** `murmurly.agentGuide()` returns a guide written for this app: its permissions, granted types and a ready tool definition. It never contains a secret. `npx @murmurly/sdk codegen` writes `murmurly.d.ts` with exact payload types.

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# @murmurly/sdk
+
+Written for whoever installs this package. Each entry says what you have to do
+differently, not what we did.
+
+`0.x` means the minor slot carries breaking changes: pin `~0.2.0` if you want
+only fixes, `^0.2.0` if you are happy to follow them.
+
+## 0.3.0
+
+**On the public npm registry.** `npm install @murmurly/sdk` works as-is: no
+`.npmrc` entry, no token.
+
+**New key format.** New keys say what they are: `murmur_id_…` is a client id,
+`murmur_secret_…` is a secret key. Keys you already have (`pk_live_…`, `app_…`,
+`sk_live_…`) keep working; nothing to change unless you issue a new one.
+
+**Breaking — `getSchema()` returns what the API actually sends.** The old type
+promised `eventTypeId`, `eventTypeName`, `eventTypeSlug` and `fields`, which
+were always `undefined`. Read them from `eventType` and `sections[].attributes`:
+
+```diff
+  const schema = await client.eventTypes.getSchema('roundtable')
+- schema.eventTypeSlug
++ schema.eventType.slug
+- schema.fields.map((f) => f.name)
++ schema.sections.flatMap((s) => s.attributes.map((a) => a.key))
+```
+
+**Breaking — `baseUrl` is required** in `createMurmurlyClient()` and
+`getAiIntegrationPrompt()`. The old default pointed at a Murmurly development
+server, not yours. Copy the URL from the app's settings page.
+
+**Breaking — a secret key refuses to run in a browser.** `createMurmurlyClient()`
+throws when given `murmur_secret_…` (or `sk_live_…`) where `window` exists. Call
+the API from your server, or use a public app's client id in the browser.
+
+**Breaking — the CLI is `murmurly`, with commands.** `npx @murmurly/sdk codegen`
+replaces `npx @murmurly/sdk murmurly-codegen` (still accepted). If you installed
+the package and ran `murmurly-codegen` directly, run `murmurly codegen`.
+
+- `--key` no longer takes a secret key: it would land in your shell history.
+  Run `npx @murmurly/sdk init`, which prompts for it unseen and saves it to a
+  git-ignored `.env.local`, or set `MURMURLY_SECRET_KEY`.
+- Environment variables are spelled `MURMURLY_…` now. The misspelt `MCRMURLY_…`
+  names still work, with a warning.
+
+**`MurmurlyEventType` fields are always present.** `description`, `color`,
+`icon` and `shortcode` were optional in the type but always sent, as `null`
+when empty. They are typed `string | null` now.
+
+**New.**
+
+- `engagements.request(payload, { idempotencyKey })` makes a retry safe: the
+  same key within 24 hours returns the first result, with `replayed: true`.
+- `engagements.list()` and `engagements.get(idOrShortcode)` read back requests
+  your app submitted (confidential apps with `engagements:read_own`).
+- `MurmurlyApiError.retryAfter` holds the seconds to wait after a `429`.
+- `getAiIntegrationPrompt()` never writes a secret key into the prompt. It
+  points the assistant at `MURMURLY_SECRET_KEY` and `init` instead.
+
+## 0.2.1
+
+No API change. This file now ships inside the package, so `node_modules/@murmurly/sdk/CHANGELOG.md`
+tells you what moved without a trip to the repository.
+
+## 0.2.0
+
+**Breaking — `engagements.request()` takes one event type field instead of two.**
+
+`eventTypeId` and `eventTypeSlug` are gone. Pass `eventType`, which accepts
+either form:
+
+```diff
+  await client.engagements.request({
+    name: 'Quarterly advisory call',
+    email: 'piet@example.com',
+    firstName: 'Piet',
+    lastName: 'de Vries',
+-   eventTypeSlug: 'advisory-call'
++   eventType: 'advisory-call'
+  })
+```
+
+It is required now, where the old pair was optional on paper — a request with
+neither was never accepted, so the type says what the API always did.
+
+**New — ask whether a type can actually be booked.**
+
+`client.eventTypes.availability({ eventType, ... })` returns the type's open
+hours and the days it will refuse, so a form can stop offering a slot the API
+would reject. Advisory, not authoritative: the request endpoint remains the
+thing that decides.
+
+```ts
+const { openHours, closedDays } = await client.eventTypes.availability({
+  eventType: 'advisory-call'
+})
+```
+
+New exported types: `EventTypeAvailability`, `OpenHours`, `ClosedDay`,
+`ClosedDayReason`.
+
+## 0.1.0
+
+First published release: `eventTypes.list()`, `eventTypes.getSchema()`,
+`engagements.request()`, `agentGuide()`, and the `murmurly-codegen` CLI.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Murmurly
+
+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

@@ -0,0 +1,108 @@
+# @murmurly/sdk
+
+Official TypeScript & JavaScript SDK for the Murmurly Public Ingestion API.
+
+Works in the browser for public apps (protected by an origin check) and on servers for confidential apps (protected by a secret key).
+
+## Installation
+
+```bash
+npm install @murmurly/sdk
+```
+
+## Keys
+
+Each app in Murmurly has keys that say what they are:
+
+| Key               | What it is                          | Where it may live                                      |
+| :---------------- | :---------------------------------- | :----------------------------------------------------- |
+| `murmur_id_…`     | Client id. A public app's whole key | Page source, browser bundles. Not a secret.            |
+| `murmur_secret_…` | Secret key of a confidential app    | Server environment only. Never in code, chat or a URL. |
+
+A public app's client id is only accepted from the origins set on the app. A confidential app's id names it but proves nothing: it authenticates with its secret key.
+
+## Store the key
+
+Run this in your own terminal. It asks for the base URL and the key, shows nothing as you type the key, checks it against the API, and saves it to `.env.local` (which it adds to `.gitignore`):
+
+```bash
+npx @murmurly/sdk init
+```
+
+In CI or on a host, set `MURMURLY_SECRET_KEY` (or `MURMURLY_CLIENT_ID`) and `MURMURLY_BASE_URL` in the platform's secret store instead.
+
+> **Using an AI coding assistant?** Have it ask you to run `init` rather than paste a secret key into the chat. The live agent guide (`client.agentGuide()`) tells assistants the same thing, and never contains a secret.
+
+## Quick start (server, confidential app)
+
+```typescript
+import { createMurmurlyClient } from '@murmurly/sdk'
+
+const murmurly = createMurmurlyClient({
+  apiKey: process.env.MURMURLY_SECRET_KEY!,
+  baseUrl: process.env.MURMURLY_BASE_URL!
+})
+
+// 1. The engagement types this app was granted
+const types = await murmurly.eventTypes.list()
+
+// 2. The fields a type's request takes
+const { sections, jsonSchema } = await murmurly.eventTypes.getSchema('roundtable')
+
+// 3. Which days the workspace can take (advisory)
+const { closedDays, earliestOpenDate } = await murmurly.eventTypes.availability({
+  eventType: 'roundtable',
+  from: '2026-10-01',
+  to: '2026-10-31'
+})
+
+// 4. Submit. The idempotency key makes a retry safe: same key, same result, no duplicate.
+const result = await murmurly.engagements.request(
+  {
+    name: 'Quarterly Strategic Offsite',
+    email: 'organizer@company.com',
+    firstName: 'Jane',
+    lastName: 'Doe',
+    eventType: 'roundtable',
+    startDate: '2026-10-20',
+    startTime: '10:00',
+    timeZone: 'America/New_York',
+    attributes: { budget: 15000, topic: 'Engineering Leadership' }
+  },
+  { idempotencyKey: crypto.randomUUID() }
+)
+
+console.log('Engagement requested:', result.eventId, result.shortcode)
+if (!result.availability.open) console.log('That date is unlikely to be approved.')
+
+// 5. Later: where it stands (needs the engagements:read_own permission)
+const request = await murmurly.engagements.get(result.shortcode)
+```
+
+## Quick start (browser, public app)
+
+```typescript
+const murmurly = createMurmurlyClient({
+  apiKey: import.meta.env.VITE_MURMURLY_CLIENT_ID, // murmur_id_…: fine in a browser bundle
+  baseUrl: import.meta.env.VITE_MURMURLY_BASE_URL
+})
+```
+
+The page's origin must be one of the app's allowed origins. From a server or script, pass `origin` explicitly: `createMurmurlyClient({ apiKey, baseUrl, origin: 'https://example.com' })`.
+
+The SDK refuses to start with a secret key in a browser.
+
+## Errors
+
+Failed calls throw `MurmurlyApiError` with the API's message and its HTTP `code`: `401` bad key, `403` wrong origin, missing permission, type not granted or app paused, `422` a field the type does not take, `429` rate limited (`retryAfter` holds the seconds to wait; retry with the same idempotency key).
+
+## CLI
+
+```bash
+npx @murmurly/sdk init      # store the key, hidden prompt
+npx @murmurly/sdk codegen   # write murmurly.d.ts for your workspace's types
+npx @murmurly/sdk guide     # print the live agent guide for this app
+npx @murmurly/sdk prompt    # print a prompt for an AI coding assistant (never contains a secret)
+```
+
+Each command reads the key from the environment or `.env.local`. `--key` accepts a public client id only: a secret key on the command line would end up in your shell history, so it is refused.

package/bin/murmurly.mjs

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+
+/**
+ * Murmurly CLI.
+ *
+ *   npx @murmurly/sdk init       Store this app's key in .env.local, prompting for it unseen
+ *   npx @murmurly/sdk codegen    Write murmurly.d.ts for the workspace's engagement types
+ *   npx @murmurly/sdk guide      Print the live agent guide for this app
+ *   npx @murmurly/sdk prompt     Print a prompt for an AI coding assistant
+ *
+ * A secret key (`murmur_secret_…`) is only ever read from the environment,
+ * from .env.local, or typed at a hidden prompt. It is never accepted as a
+ * command-line argument (shell history, process lists, CI logs) and never
+ * printed: output shows its first few characters at most.
+ */
+
+import { existsSync, readFileSync, writeFileSync, appendFileSync, chmodSync } from 'node:fs'
+import { resolve } from 'node:path'
+import process from 'node:process'
+import { createInterface } from 'node:readline/promises'
+
+import { getAiIntegrationPrompt, isSecretKey } from '../dist/index.js'
+
+const DEFAULT_ENV_FILE = '.env.local'
+const ENV = {
+  secret: 'MURMURLY_SECRET_KEY',
+  clientId: 'MURMURLY_CLIENT_ID',
+  baseUrl: 'MURMURLY_BASE_URL',
+  origin: 'MURMURLY_ORIGIN'
+}
+/** Misspelt names 0.2.x read. Still honoured, with a warning, so nothing breaks on upgrade. */
+const LEGACY_ENV = {
+  key: 'MCRMURLY_API_KEY',
+  baseUrl: 'MCRMURLY_BASE_URL',
+  origin: 'MCRMURLY_ORIGIN'
+}
+
+const USAGE = `Usage: npx @murmurly/sdk <command> [options]
+
+Commands:
+  init      Store this app's key and base URL in ${DEFAULT_ENV_FILE}. Prompts for the key
+            without showing it, checks it against the API, and keeps the file out of git.
+  codegen   Write TypeScript declarations for your workspace (default: murmurly.d.ts).
+  guide     Print the live agent guide for this app.
+  prompt    Print a prompt for an AI coding assistant. Never contains a secret key.
+
+Options:
+  --url <url>          API base URL (else ${ENV.baseUrl}, else ${DEFAULT_ENV_FILE})
+  --origin <origin>    Origin to send, for a public app's client id
+  --key <client-id>    A public client id. Secret keys are refused here: use init.
+  --env-file <path>    Where init stores the key (default: ${DEFAULT_ENV_FILE})
+  --out <file>         Where codegen writes (default: murmurly.d.ts)`
+
+// ---------------------------------------------------------------------------
+// Arguments and configuration
+// ---------------------------------------------------------------------------
+
+const COMMAND_ALIASES = {
+  'murmurly-codegen': 'codegen',
+  '--ai-prompt': 'prompt',
+  '--guide': 'guide'
+}
+const COMMANDS = new Set(['init', 'codegen', 'guide', 'prompt', 'help'])
+
+function flag(args, name) {
+  const index = args.indexOf(name)
+  return index !== -1 && index + 1 < args.length ? args[index + 1] : undefined
+}
+
+function commandFrom(args) {
+  const words = args.filter((a) => !a.startsWith('--') || COMMAND_ALIASES[a])
+  const named = words.map((w) => COMMAND_ALIASES[w] ?? w).find((w) => COMMANDS.has(w))
+  if (named) return named
+  return args.includes('--help') || args.includes('-h') ? 'help' : 'codegen'
+}
+
+/** KEY=value lines; quotes stripped. Enough for the file init writes. */
+function readEnvFile(path) {
+  if (!existsSync(path)) return {}
+  const entries = readFileSync(path, 'utf8')
+    .split('\n')
+    .map((line) => /^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/.exec(line))
+    .filter(Boolean)
+    .map(([, key, value]) => [key, value.replace(/^(['"])(.*)\1$/, '$2')])
+  return Object.fromEntries(entries)
+}
+
+function legacy(name) {
+  const value = process.env[name]
+  if (value) console.warn(`Warning: ${name} is deprecated; rename it to the MURMURLY_ equivalent.`)
+  return value
+}
+
+function refuseSecretOnCommandLine(key) {
+  if (!key || !isSecretKey(key)) return
+  console.error(
+    'Refusing a secret key on the command line: it would end up in your shell history.\n' +
+      `Run \`npx @murmurly/sdk init\` to store it, or set ${ENV.secret} in the environment.`
+  )
+  process.exit(1)
+}
+
+function resolveConfig(args) {
+  const fileEnv = readEnvFile(resolve(process.cwd(), flag(args, '--env-file') ?? DEFAULT_ENV_FILE))
+  const pick = (name) => process.env[name] || fileEnv[name]
+  const flagKey = flag(args, '--key')
+  refuseSecretOnCommandLine(flagKey)
+  return {
+    key: flagKey || pick(ENV.secret) || pick(ENV.clientId) || legacy(LEGACY_ENV.key),
+    baseUrl: flag(args, '--url') || pick(ENV.baseUrl) || legacy(LEGACY_ENV.baseUrl),
+    origin: flag(args, '--origin') || pick(ENV.origin) || legacy(LEGACY_ENV.origin)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Prompts
+// ---------------------------------------------------------------------------
+
+async function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    return (await rl.question(question)).trim()
+  } finally {
+    rl.close()
+  }
+}
+
+/** Reads a line from the terminal without echoing it. Pasting works. */
+function askHidden(question) {
+  const { stdin, stdout } = process
+  stdout.write(question)
+  stdin.setRawMode(true)
+  stdin.setEncoding('utf8')
+  return new Promise((resolvePrompt) => {
+    let value = ''
+    const finish = () => {
+      stdin.setRawMode(false)
+      stdin.pause()
+      stdin.off('data', onData)
+      stdout.write('\n')
+      resolvePrompt(value.trim())
+    }
+    const onData = (chunk) => {
+      for (const char of chunk) {
+        if (char === '') process.exit(130)
+        if (char === '\r' || char === '\n' || char === '') return finish()
+        value = char === '' || char === '\b' ? value.slice(0, -1) : value + char
+      }
+    }
+    // Listen before resuming, or input already buffered is lost.
+    stdin.on('data', onData)
+    stdin.resume()
+  })
+}
+
+function requireTerminal() {
+  if (process.stdin.isTTY) return
+  console.error(
+    'This needs an interactive terminal, so the key can be typed without being shown.\n' +
+      `In CI or on a host, set ${ENV.secret} (or ${ENV.clientId}) and ${ENV.baseUrl} in its secret store instead.`
+  )
+  process.exit(1)
+}
+
+const preview = (key) => `${key.slice(0, isSecretKey(key) ? 22 : 18)}…`
+
+// ---------------------------------------------------------------------------
+// API
+// ---------------------------------------------------------------------------
+
+function headersFor(key, origin) {
+  const headers = { 'x-api-key': key }
+  if (origin) headers.Origin = origin
+  return headers
+}
+
+async function fetchOrExit(url, key, origin, what) {
+  const res = await fetch(url, { headers: headersFor(key, origin) })
+  if (res.ok) return res
+  let message = `${res.status} ${res.statusText}`
+  try {
+    message = (await res.json())?.error?.message ?? message
+  } catch {
+    // Not JSON: keep the status line.
+  }
+  console.error(`Could not ${what}: ${message}`)
+  process.exit(1)
+}
+
+function requireKeyAndUrl({ key, baseUrl }) {
+  if (key && baseUrl) return
+  console.error(
+    `Missing ${key ? 'base URL' : 'key'}. Run \`npx @murmurly/sdk init\` first, ` +
+      `or set ${key ? ENV.baseUrl : `${ENV.secret} / ${ENV.clientId}`}.`
+  )
+  process.exit(1)
+}
+
+const trimSlash = (url) => url.replace(/\/+$/, '')
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+/** Sets each KEY in the file, replacing an existing line or appending one. */
+function writeEnvValues(path, values) {
+  let text = existsSync(path) ? readFileSync(path, 'utf8') : ''
+  for (const [name, value] of Object.entries(values)) {
+    const line = `${name}=${value}`
+    const pattern = new RegExp(`^${name}=.*$`, 'm')
+    text = pattern.test(text)
+      ? text.replace(pattern, line)
+      : `${text}${text && !text.endsWith('\n') ? '\n' : ''}${line}\n`
+  }
+  writeFileSync(path, text, { mode: 0o600 })
+  chmodSync(path, 0o600)
+}
+
+/** Adds the env file to .gitignore when this is a git checkout and it is not listed yet. */
+function keepOutOfGit(envFile) {
+  const gitignore = resolve(process.cwd(), '.gitignore')
+  if (!existsSync(resolve(process.cwd(), '.git')) && !existsSync(gitignore)) return
+  const listed =
+    existsSync(gitignore) &&
+    readFileSync(gitignore, 'utf8')
+      .split('\n')
+      .some((l) => l.trim() === envFile)
+  if (listed) return
+  appendFileSync(gitignore, `\n# Murmurly API key\n${envFile}\n`)
+  console.log(`Added ${envFile} to .gitignore.`)
+}
+
+/** Base URL, key and (for a client id) origin, asked for where no flag gave them. */
+async function askInitInputs(args) {
+  const baseUrl = trimSlash(
+    flag(args, '--url') || (await ask('API base URL (from the app settings page): '))
+  )
+  const key = await askHidden('App key (input hidden): ')
+  if (!baseUrl || !key) {
+    console.error('Nothing saved: the base URL and key are both needed.')
+    process.exit(1)
+  }
+  if (isSecretKey(key)) return { baseUrl, key, secret: true }
+  const origin =
+    flag(args, '--origin') ||
+    (await ask('An allowed origin for this app, e.g. https://example.com: '))
+  return { baseUrl, key, secret: false, origin }
+}
+
+async function runInit(args) {
+  requireTerminal()
+  const envFile = flag(args, '--env-file') ?? DEFAULT_ENV_FILE
+  const { baseUrl, key, secret, origin } = await askInitInputs(args)
+  const res = await fetchOrExit(`${baseUrl}/api/v1/event-types`, key, origin, 'verify the key')
+  const { eventTypes = [] } = await res.json()
+
+  const keyVariable = secret ? ENV.secret : ENV.clientId
+  const values = { [ENV.baseUrl]: baseUrl, [keyVariable]: key }
+  if (origin) values[ENV.origin] = origin
+  writeEnvValues(resolve(process.cwd(), envFile), values)
+  keepOutOfGit(envFile)
+
+  console.log(`Verified ${preview(key)}: ${eventTypes.length} engagement type(s) granted.`)
+  console.log(`Saved to ${envFile} as ${keyVariable}.`)
+  if (secret) console.log('Read it on the server only: process.env.MURMURLY_SECRET_KEY')
+}
+
+async function runCodegen(args) {
+  const config = resolveConfig(args)
+  requireKeyAndUrl(config)
+  const out = resolve(process.cwd(), flag(args, '--out') ?? 'murmurly.d.ts')
+  const url = `${trimSlash(config.baseUrl)}/api/v1/types.d.ts`
+  const res = await fetchOrExit(url, config.key, config.origin, 'download types')
+  writeFileSync(out, await res.text(), 'utf-8')
+  console.log(`Wrote TypeScript declarations to ${out}`)
+}
+
+async function runGuide(args) {
+  const config = resolveConfig(args)
+  requireKeyAndUrl(config)
+  const url = `${trimSlash(config.baseUrl)}/api/v1/agent-guide`
+  const res = await fetchOrExit(url, config.key, config.origin, 'fetch the agent guide')
+  console.log(await res.text())
+}
+
+function runPrompt(args) {
+  const config = resolveConfig(args)
+  requireKeyAndUrl(config)
+  console.log(
+    getAiIntegrationPrompt({ apiKey: config.key, baseUrl: config.baseUrl, origin: config.origin })
+  )
+}
+
+const RUNNERS = {
+  init: runInit,
+  codegen: runCodegen,
+  guide: runGuide,
+  prompt: runPrompt,
+  help: () => console.log(USAGE)
+}
+
+const args = process.argv.slice(2)
+Promise.resolve(RUNNERS[commandFrom(args)](args)).catch((err) => {
+  console.error('Unexpected error:', err instanceof Error ? err.message : err)
+  process.exit(1)
+})

package/dist/client.d.ts

@@ -0,0 +1,281 @@
+/** Prefix of a client id: names an app. For a public app it is the whole key. Not secret. */
+export declare const CLIENT_ID_PREFIX = "murmur_id_";
+/** Prefix of a secret key: proves a confidential app is who it says. Server-side only. */
+export declare const SECRET_KEY_PREFIX = "murmur_secret_";
+/** Whether a key is a secret key (`murmur_secret_…`, or a legacy `sk_live_…`). */
+export declare function isSecretKey(key: string): boolean;
+export interface MurmurlyClientOptions {
+    /**
+     * The app's key: its client id (`murmur_id_…`) for a public app, its secret
+     * key (`murmur_secret_…`) for a confidential one. Read a secret from the
+     * environment (`process.env.MURMURLY_SECRET_KEY`); never hard-code it.
+     */
+    apiKey: string;
+    /**
+     * The API's base URL, shown on the app's settings page in Murmurly
+     * (e.g. `https://<deployment>.convex.site`).
+     */
+    baseUrl: string;
+    /**
+     * The `Origin` to send. Public apps only, and only outside a browser: a
+     * browser sends its own and ignores this.
+     */
+    origin?: string;
+    /**
+     * Custom fetch implementation (defaults to global fetch).
+     */
+    fetch?: typeof fetch;
+}
+export interface MurmurlyEventType {
+    /** Unique ID of the event/engagement type */
+    id: string;
+    /** Human-readable title (e.g. "Product Demo", "Advisory Call") */
+    name: string;
+    /** URL-friendly slug */
+    slug: string;
+    /** Description or briefing */
+    description: string | null;
+    /** Brand color token or hex */
+    color: string | null;
+    /** Icon identifier */
+    icon: string | null;
+    /** Unique shortcode identifier */
+    shortcode: string | null;
+}
+export interface FormSchemaField {
+    /** The key to send under `attributes`. */
+    key: string;
+    label: string;
+    description: string | null;
+    /** Attribute type, e.g. `text`, `number`, `select`. */
+    type: string;
+    required: boolean;
+    /** Type-specific settings, e.g. the options of a `select`. */
+    config: unknown;
+}
+export interface FormSchemaSection {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    attributes: FormSchemaField[];
+}
+export interface EventTypeFormSchema {
+    eventType: MurmurlyEventType;
+    /** The request form's sections, as this app may see them. */
+    sections: FormSchemaSection[];
+    /** JSON Schema (draft 2020-12) for the whole request body, `attributes` included. */
+    jsonSchema: Record<string, unknown>;
+}
+export interface EngagementRequestPayload<TAttributes extends Record<string, unknown> = Record<string, unknown>> {
+    /** Title or subject of the requested engagement */
+    name: string;
+    /** Requester email address */
+    email: string;
+    /** Requester first name */
+    firstName: string;
+    /** Requester last name */
+    lastName: string;
+    /** Context, background, or goals */
+    description?: string;
+    /** Event type slug (e.g. "roundtable") or id */
+    eventType: string;
+    /** Preferred first day (YYYY-MM-DD) in the workspace's calendar */
+    startDate: string;
+    /** Preferred start time (HH:mm) on the requester's clock, within the type's `openHours` */
+    startTime?: string;
+    /** Last day (YYYY-MM-DD), for types that allow multi-day requests */
+    endDate?: string;
+    /** The requester's IANA time zone, e.g. "America/New_York" */
+    timeZone?: string;
+    /** Custom attribute values matching the event type's schema */
+    attributes?: TAttributes;
+}
+export interface EngagementRequestOptions {
+    /**
+     * Makes the submission safe to retry: the same key within 24 hours returns
+     * the first result (`replayed: true`) instead of creating a duplicate.
+     * Generate one per submission and reuse it for that submission's retries.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * Why a day is closed. `unavailable` covers both the type's schedule and
+ * workspace closures; the workspace decides whether a closure's name is shown.
+ */
+export type ClosedDayReason = 'unavailable' | 'tooSoon' | 'tooFar';
+export interface ClosedDay {
+    date: string;
+    reason: ClosedDayReason;
+    labels: string[];
+}
+export interface OpenHours {
+    /** `09:00`, on the workspace clock. */
+    start: string;
+    /** `17:00`, on the workspace clock. */
+    end: string;
+}
+export interface EventTypeAvailability {
+    /** The workspace's time zone; every date and time of day is read in it. */
+    timeZone: string;
+    today: string;
+    earliestOpenDate: string | null;
+    /** Closed days in the range; every other day is open. */
+    closedDays: ClosedDay[];
+    /** Times of day this type can start. Empty means any time works. */
+    openHours: OpenHours[];
+    /** How long one of these runs, when the type says so. */
+    durationMinutes: number | null;
+}
+export interface EngagementRequestResult {
+    success: boolean;
+    /** True when an earlier submission with the same idempotency key was returned instead. */
+    replayed?: boolean;
+    eventId: string;
+    shortcode: string;
+    /** Advisory: a request on a closed day, or outside the hours, is still created. */
+    availability: {
+        open: boolean;
+        closedDays: ClosedDay[];
+        timeOpen: boolean;
+    };
+    allowedOrigins: string[];
+}
+/** A request this app submitted: where it stands and what it asked for. */
+export interface OwnEngagementRequest {
+    id: string;
+    shortcode: string;
+    /** e.g. `requested`, `approved`, `rejected`, `confirmed`. */
+    status: string;
+    name: string;
+    eventType?: string;
+    startDate?: string;
+    endDate?: string;
+    startTime?: string;
+    submittedAt?: string;
+}
+export declare class MurmurlyApiError extends Error {
+    code: number;
+    /** Seconds to wait before retrying, when the API said so (`429`). */
+    retryAfter?: number;
+    constructor(message: string, code?: number, retryAfter?: number);
+}
+/**
+ * Main client interface for Murmurly Public Ingestion API.
+ *
+ * @example
+ * ```typescript
+ * import { createMurmurlyClient } from '@murmurly/sdk'
+ *
+ * // Server-side, confidential app. The secret comes from the environment.
+ * const murmurly = createMurmurlyClient({
+ *   apiKey: process.env.MURMURLY_SECRET_KEY!,
+ *   baseUrl: process.env.MURMURLY_BASE_URL!
+ * })
+ *
+ * const types = await murmurly.eventTypes.list()
+ * const booking = await murmurly.engagements.request(
+ *   {
+ *     name: 'Discovery Consultation',
+ *     email: 'client@example.com',
+ *     firstName: 'Jane',
+ *     lastName: 'Doe',
+ *     eventType: types[0].slug,
+ *     startDate: '2026-10-20'
+ *   },
+ *   { idempotencyKey: crypto.randomUUID() }
+ * )
+ * ```
+ */
+export interface MurmurlyClient {
+    /**
+     * Discovery methods for retrieving public engagement types and attribute schemas.
+     */
+    eventTypes: {
+        /**
+         * Lists the engagement types this app has been granted.
+         */
+        list: () => Promise<MurmurlyEventType[]>;
+        /**
+         * The request form of one type: its fields and a JSON Schema for the request body.
+         */
+        getSchema: (slugOrId: string | {
+            slug?: string;
+            id?: string;
+        }) => Promise<EventTypeFormSchema>;
+        /**
+         * Which days a type can take. Advisory: a request on a closed day is still accepted.
+         */
+        availability: (query: {
+            eventType: string;
+            from: string;
+            to: string;
+        }) => Promise<EventTypeAvailability>;
+    };
+    /**
+     * Methods for booking and requesting engagements.
+     */
+    engagements: {
+        /**
+         * Submits an engagement request.
+         *
+         * @throws {MurmurlyApiError} 400 (malformed), 401 (invalid key), 403 (origin, scope or
+         * type not granted), 422 (field the type does not take), 429 (rate limited; see `retryAfter`).
+         */
+        request: <TAttributes extends Record<string, unknown> = Record<string, unknown>>(payload: EngagementRequestPayload<TAttributes>, options?: EngagementRequestOptions) => Promise<EngagementRequestResult>;
+        /**
+         * The latest 50 requests this app submitted. Confidential apps with `engagements:read_own`.
+         */
+        list: () => Promise<OwnEngagementRequest[]>;
+        /**
+         * One request this app submitted, by id or shortcode. Confidential apps with `engagements:read_own`.
+         */
+        get: (idOrShortcode: string) => Promise<OwnEngagementRequest>;
+    };
+    /**
+     * Type definitions synchronization.
+     */
+    types: {
+        /**
+         * Downloads TypeScript declaration file for the connected workspace.
+         */
+        download: () => Promise<string>;
+    };
+    /**
+     * Fetches real-time dynamic Markdown documentation tailored to this application key.
+     * AI agents can query this endpoint to inspect active schemas at runtime. It never contains a secret.
+     */
+    agentGuide: () => Promise<string>;
+}
+/**
+ * Creates a strongly typed Murmurly client for interacting with the Public API.
+ */
+export declare function createMurmurlyClient(options: MurmurlyClientOptions): MurmurlyClient;
+export interface AiPromptOptions {
+    /**
+     * A public app's client id (`murmur_id_…`) is written into the prompt. A
+     * secret key never is: the prompt tells the assistant to read it from
+     * `MURMURLY_SECRET_KEY` and have the user store it with `murmurly init`.
+     */
+    apiKey: string;
+    baseUrl: string;
+    origin?: string;
+    appName?: string;
+}
+/**
+ * Generates an instruction prompt for AI assistants (Cursor, Claude, Copilot, Lovable, Bolt.new).
+ * The prompt never contains a secret key, whatever `apiKey` holds.
+ */
+export declare function getAiIntegrationPrompt(options: AiPromptOptions): string;
+/**
+ * Contextual hints and architecture notes for AI agents inspecting this library.
+ */
+export declare const AI_INTEGRATION_HINTS: {
+    readonly description: "Official TypeScript client for Murmurly Public Ingestion API";
+    readonly coreMethods: readonly ["createMurmurlyClient({ apiKey, baseUrl, origin })", "client.eventTypes.list() - engagement types this app was granted", "client.eventTypes.getSchema(slugOrId) - { eventType, sections, jsonSchema } for one type", "client.eventTypes.availability({ eventType, from, to }) - closed days, advisory", "client.engagements.request(payload, { idempotencyKey }) - submit a request", "client.engagements.list() / get(idOrShortcode) - read back own requests (confidential apps)", "client.agentGuide() - real-time Markdown guide for this app, never contains a secret"];
+    readonly keyFormats: "murmur_id_… is a client id (public, safe in page source). murmur_secret_… is a secret key (server-only).";
+    readonly securityNote: "Never ask a user to paste a secret key into chat or code. Have them run `npx @murmurly/sdk init`, then read process.env.MURMURLY_SECRET_KEY on the server.";
+    readonly cliSetup: "npx @murmurly/sdk init";
+    readonly cliCodegen: "npx @murmurly/sdk codegen";
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -0,0 +1,185 @@
+/** Prefix of a client id: names an app. For a public app it is the whole key. Not secret. */
+export const CLIENT_ID_PREFIX = 'murmur_id_';
+/** Prefix of a secret key: proves a confidential app is who it says. Server-side only. */
+export const SECRET_KEY_PREFIX = 'murmur_secret_';
+/** Whether a key is a secret key (`murmur_secret_…`, or a legacy `sk_live_…`). */
+export function isSecretKey(key) {
+    return key.startsWith(SECRET_KEY_PREFIX) || key.startsWith('sk_live_');
+}
+export class MurmurlyApiError extends Error {
+    code;
+    /** Seconds to wait before retrying, when the API said so (`429`). */
+    retryAfter;
+    constructor(message, code = 500, retryAfter) {
+        super(message);
+        this.name = 'MurmurlyApiError';
+        this.code = code;
+        this.retryAfter = retryAfter;
+    }
+}
+const isBrowser = () => typeof window !== 'undefined' && typeof document !== 'undefined';
+function readOptions(options) {
+    const key = typeof options.apiKey === 'string' ? options.apiKey.trim() : '';
+    if (!key)
+        throw new Error('MurmurlyClient requires a valid apiKey.');
+    if (isSecretKey(key) && isBrowser()) {
+        throw new Error('A Murmurly secret key must never reach a browser. Call the API from your server, ' +
+            'or use a public app and its client id (murmur_id_…) here.');
+    }
+    const baseUrl = typeof options.baseUrl === 'string' ? options.baseUrl.trim() : '';
+    if (!baseUrl) {
+        throw new Error('MurmurlyClient requires a baseUrl: copy it from the app settings page in Murmurly.');
+    }
+    return { key, baseUrl: baseUrl.replace(/\/+$/, '') };
+}
+async function toApiError(res, fallback) {
+    const retryAfterHeader = res.headers?.get?.('Retry-After');
+    const retryAfter = retryAfterHeader ? Number(retryAfterHeader) : undefined;
+    let message = `${fallback} (HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ''})`;
+    try {
+        const body = (await res.json());
+        if (body?.error?.message)
+            message = body.error.message;
+    }
+    catch {
+        // Not JSON: keep the status line.
+    }
+    return new MurmurlyApiError(message, res.status, retryAfter);
+}
+/**
+ * Creates a strongly typed Murmurly client for interacting with the Public API.
+ */
+export function createMurmurlyClient(options) {
+    const { key, baseUrl } = readOptions(options);
+    const { origin, fetch: customFetch = globalThis.fetch } = options;
+    function buildHeaders(extraHeaders = {}) {
+        const headers = { 'x-api-key': key, ...extraHeaders };
+        if (origin)
+            headers.Origin = origin;
+        return headers;
+    }
+    async function call(path, init = {}) {
+        const headers = buildHeaders(init.headers || {});
+        const res = await customFetch(`${baseUrl}${path}`, { ...init, headers });
+        if (!res.ok)
+            throw await toApiError(res, 'Murmurly API request failed');
+        return res;
+    }
+    const json = async (path, init) => (await (await call(path, init)).json());
+    const text = async (path) => (await call(path)).text();
+    return {
+        eventTypes: {
+            async list() {
+                const data = await json('/api/v1/event-types');
+                return data.eventTypes ?? [];
+            },
+            async getSchema(slugOrId) {
+                const ref = typeof slugOrId === 'string' ? { slug: slugOrId } : slugOrId;
+                const params = new URLSearchParams();
+                if (ref.slug)
+                    params.set('slug', ref.slug);
+                if (!ref.slug && ref.id)
+                    params.set('id', ref.id);
+                return json(`/api/v1/event-types/schema?${params}`);
+            },
+            async availability(query) {
+                const params = new URLSearchParams(query);
+                return json(`/api/v1/event-types/availability?${params}`);
+            }
+        },
+        engagements: {
+            async request(payload, requestOptions = {}) {
+                const headers = { 'Content-Type': 'application/json' };
+                if (requestOptions.idempotencyKey)
+                    headers['Idempotency-Key'] = requestOptions.idempotencyKey;
+                return json('/api/v1/engagements/request', {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(payload)
+                });
+            },
+            async list() {
+                const data = await json('/api/v1/engagements/requests');
+                return data.requests ?? [];
+            },
+            async get(idOrShortcode) {
+                const params = new URLSearchParams({ id: idOrShortcode });
+                return json(`/api/v1/engagements/requests?${params}`);
+            }
+        },
+        types: {
+            download: () => text('/api/v1/types.d.ts')
+        },
+        agentGuide: () => text('/api/v1/agent-guide')
+    };
+}
+/**
+ * Generates an instruction prompt for AI assistants (Cursor, Claude, Copilot, Lovable, Bolt.new).
+ * The prompt never contains a secret key, whatever `apiKey` holds.
+ */
+export function getAiIntegrationPrompt(options) {
+    const { apiKey, baseUrl, origin, appName = 'My App' } = options;
+    const cleanBase = baseUrl.replace(/\/+$/, '');
+    const secret = isSecretKey(apiKey.trim());
+    const keyExpression = secret ? 'process.env.MURMURLY_SECRET_KEY' : `'${apiKey.trim()}'`;
+    const keyLine = secret
+        ? '- Secret key: stored by the user in MURMURLY_SECRET_KEY (server-side only). Never ask for it in chat or write it into code.'
+        : `- Client id (public, safe in page source): ${apiKey.trim()}`;
+    const setupStep = secret
+        ? `\n0. Ask the user to run this in their own terminal. It prompts for the secret key without echoing it
+   and saves it to a git-ignored .env.local:
+   npx @murmurly/sdk init --url ${cleanBase}\n`
+        : '';
+    const originLine = origin ? `\n- Allowed Origin: ${origin}` : '';
+    const originNote = secret
+        ? 'Call Murmurly from server code only: the SDK refuses to run a secret key in a browser.'
+        : `Ensure '${origin || 'your website origin'}' is configured in Allowed CORS Domains in Murmurly Settings.`;
+    return `Integrate Murmurly public engagement booking into "${appName}".
+
+API Configuration:
+- Base URL: ${cleanBase}
+${keyLine}${originLine}
+
+Integration Steps:${setupStep}
+1. Install official SDK:
+   npm install @murmurly/sdk
+
+2. Query live engagement types:
+   import { createMurmurlyClient } from '@murmurly/sdk'
+   const client = createMurmurlyClient({ apiKey: ${keyExpression}, baseUrl: '${cleanBase}' })
+   const eventTypes = await client.eventTypes.list()
+
+3. Read the chosen type's fields: await client.eventTypes.getSchema(slug)
+
+4. Submit the request, with a fresh idempotency key per submission:
+   await client.engagements.request({
+     name: 'Meeting Title',
+     email: 'guest@example.com',
+     firstName: 'First',
+     lastName: 'Last',
+     eventType: eventTypes[0].slug,
+     startDate: '2026-10-20'
+   }, { idempotencyKey: crypto.randomUUID() })
+
+Note: ${originNote}`;
+}
+/**
+ * Contextual hints and architecture notes for AI agents inspecting this library.
+ */
+export const AI_INTEGRATION_HINTS = {
+    description: 'Official TypeScript client for Murmurly Public Ingestion API',
+    coreMethods: [
+        'createMurmurlyClient({ apiKey, baseUrl, origin })',
+        'client.eventTypes.list() - engagement types this app was granted',
+        'client.eventTypes.getSchema(slugOrId) - { eventType, sections, jsonSchema } for one type',
+        'client.eventTypes.availability({ eventType, from, to }) - closed days, advisory',
+        'client.engagements.request(payload, { idempotencyKey }) - submit a request',
+        'client.engagements.list() / get(idOrShortcode) - read back own requests (confidential apps)',
+        'client.agentGuide() - real-time Markdown guide for this app, never contains a secret'
+    ],
+    keyFormats: 'murmur_id_… is a client id (public, safe in page source). murmur_secret_… is a secret key (server-only).',
+    securityNote: 'Never ask a user to paste a secret key into chat or code. Have them run `npx @murmurly/sdk init`, then read process.env.MURMURLY_SECRET_KEY on the server.',
+    cliSetup: 'npx @murmurly/sdk init',
+    cliCodegen: 'npx @murmurly/sdk codegen'
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAA;AAC5C,0FAA0F;AAC1F,MAAM,CAAC,MAAM,iBAAiB,GAAG,gBAAgB,CAAA;AAEjD,kFAAkF;AAClF,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,CAAA;AACxE,CAAC;AAsKD,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,IAAI,CAAQ;IACZ,qEAAqE;IACrE,UAAU,CAAS;IACnB,YAAY,OAAe,EAAE,OAAe,GAAG,EAAE,UAAmB;QAClE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAA;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC9B,CAAC;CACF;AA6FD,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,QAAQ,KAAK,WAAW,CAAA;AAExF,SAAS,WAAW,CAAC,OAA8B;IACjD,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAC3E,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAA;IACpE,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,SAAS,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACb,mFAAmF;YACjF,2DAA2D,CAC9D,CAAA;IACH,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IACjF,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,oFAAoF,CACrF,CAAA;IACH,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAA;AACtD,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,GAAa,EAAE,QAAgB;IACvD,MAAM,gBAAgB,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,CAAA;IAC1D,MAAM,UAAU,GAAG,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAC1E,IAAI,OAAO,GAAG,GAAG,QAAQ,UAAU,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAA;IAC7F,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAqC,CAAA;QACnE,IAAI,IAAI,EAAE,KAAK,EAAE,OAAO;YAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAA;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,kCAAkC;IACpC,CAAC;IACD,OAAO,IAAI,gBAAgB,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;AAC9D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAA8B;IACjE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;IAC7C,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,UAAU,CAAC,KAAK,EAAE,GAAG,OAAO,CAAA;IAEjE,SAAS,YAAY,CAAC,eAAuC,EAAE;QAC7D,MAAM,OAAO,GAA2B,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,YAAY,EAAE,CAAA;QAC7E,IAAI,MAAM;YAAE,OAAO,CAAC,MAAM,GAAG,MAAM,CAAA;QACnC,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,KAAK,UAAU,IAAI,CAAC,IAAY,EAAE,OAAoB,EAAE;QACtD,MAAM,OAAO,GAAG,YAAY,CAAE,IAAI,CAAC,OAAkC,IAAI,EAAE,CAAC,CAAA;QAC5E,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,GAAG,OAAO,GAAG,IAAI,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAA;QACxE,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,MAAM,UAAU,CAAC,GAAG,EAAE,6BAA6B,CAAC,CAAA;QACvE,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,EAAK,IAAY,EAAE,IAAkB,EAAc,EAAE,CACrE,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAM,CAAA;IAE9C,MAAM,IAAI,GAAG,KAAK,EAAE,IAAY,EAAmB,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAE/E,OAAO;QACL,UAAU,EAAE;YACV,KAAK,CAAC,IAAI;gBACR,MAAM,IAAI,GAAG,MAAM,IAAI,CAAsC,qBAAqB,CAAC,CAAA;gBACnF,OAAO,IAAI,CAAC,UAAU,IAAI,EAAE,CAAA;YAC9B,CAAC;YAED,KAAK,CAAC,SAAS,CACb,QAAiD;gBAEjD,MAAM,GAAG,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAA;gBACxE,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAA;gBACpC,IAAI,GAAG,CAAC,IAAI;oBAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,CAAA;gBAC1C,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE;oBAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,CAAA;gBACjD,OAAO,IAAI,CAAsB,8BAA8B,MAAM,EAAE,CAAC,CAAA;YAC1E,CAAC;YAED,KAAK,CAAC,YAAY,CAAC,KAIlB;gBACC,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,CAAA;gBACzC,OAAO,IAAI,CAAwB,oCAAoC,MAAM,EAAE,CAAC,CAAA;YAClF,CAAC;SACF;QAED,WAAW,EAAE;YACX,KAAK,CAAC,OAAO,CACX,OAA8C,EAC9C,iBAA2C,EAAE;gBAE7C,MAAM,OAAO,GAA2B,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAA;gBAC9E,IAAI,cAAc,CAAC,cAAc;oBAC/B,OAAO,CAAC,iBAAiB,CAAC,GAAG,cAAc,CAAC,cAAc,CAAA;gBAC5D,OAAO,IAAI,CAA0B,6BAA6B,EAAE;oBAClE,MAAM,EAAE,MAAM;oBACd,OAAO;oBACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;iBAC9B,CAAC,CAAA;YACJ,CAAC;YAED,KAAK,CAAC,IAAI;gBACR,MAAM,IAAI,GAAG,MAAM,IAAI,CACrB,8BAA8B,CAC/B,CAAA;gBACD,OAAO,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAA;YAC5B,CAAC;YAED,KAAK,CAAC,GAAG,CAAC,aAAqB;gBAC7B,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,EAAE,EAAE,aAAa,EAAE,CAAC,CAAA;gBACzD,OAAO,IAAI,CAAuB,gCAAgC,MAAM,EAAE,CAAC,CAAA;YAC7E,CAAC;SACF;QAED,KAAK,EAAE;YACL,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,oBAAoB,CAAC;SAC3C;QAED,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,qBAAqB,CAAC;KAC9C,CAAA;AACH,CAAC;AAcD;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAwB;IAC7D,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAA;IAC/D,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAC7C,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;IACzC,MAAM,aAAa,GAAG,MAAM,CAAC,CAAC,CAAC,iCAAiC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,EAAE,GAAG,CAAA;IACvF,MAAM,OAAO,GAAG,MAAM;QACpB,CAAC,CAAC,6HAA6H;QAC/H,CAAC,CAAC,8CAA8C,MAAM,CAAC,IAAI,EAAE,EAAE,CAAA;IACjE,MAAM,SAAS,GAAG,MAAM;QACtB,CAAC,CAAC;;kCAE4B,SAAS,IAAI;QAC3C,CAAC,CAAC,EAAE,CAAA;IACN,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,uBAAuB,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAChE,MAAM,UAAU,GAAG,MAAM;QACvB,CAAC,CAAC,wFAAwF;QAC1F,CAAC,CAAC,WAAW,MAAM,IAAI,qBAAqB,+DAA+D,CAAA;IAE7G,OAAO,sDAAsD,OAAO;;;cAGxD,SAAS;EACrB,OAAO,GAAG,UAAU;;oBAEF,SAAS;;;;;;mDAMsB,aAAa,eAAe,SAAS;;;;;;;;;;;;;;;QAehF,UAAU,EAAE,CAAA;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,WAAW,EAAE,8DAA8D;IAC3E,WAAW,EAAE;QACX,mDAAmD;QACnD,kEAAkE;QAClE,0FAA0F;QAC1F,iFAAiF;QACjF,4EAA4E;QAC5E,6FAA6F;QAC7F,sFAAsF;KACvF;IACD,UAAU,EACR,0GAA0G;IAC5G,YAAY,EACV,4JAA4J;IAC9J,QAAQ,EAAE,wBAAwB;IAClC,UAAU,EAAE,2BAA2B;CAC/B,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './client.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA"}

package/llms.txt

@@ -0,0 +1,47 @@
+# @murmurly/sdk
+
+> Official client SDK and CLI for the Murmurly Public Ingestion API.
+
+## Overview
+A typed client for submitting engagement requests to a Murmurly workspace. Runs in browsers (public apps, protected by an origin check) and on servers (confidential apps, protected by a secret key).
+
+## Installation
+```bash
+npm install @murmurly/sdk
+```
+
+## Keys
+- `murmur_id_…`: client id. A public app's whole key; safe in page source.
+- `murmur_secret_…`: secret key. Server-side only. Never ask a user to paste it into chat; never write it into code, prompts, logs or URLs.
+
+To store a key, the user runs `npx @murmurly/sdk init` in their own terminal. It prompts without echoing, verifies the key, and saves `MURMURLY_SECRET_KEY` (or `MURMURLY_CLIENT_ID`) and `MURMURLY_BASE_URL` to a git-ignored `.env.local`.
+
+## Quick Start
+```typescript
+import { createMurmurlyClient } from '@murmurly/sdk'
+
+const murmurly = createMurmurlyClient({
+  apiKey: process.env.MURMURLY_SECRET_KEY!,
+  baseUrl: process.env.MURMURLY_BASE_URL!
+})
+
+const eventTypes = await murmurly.eventTypes.list()
+const { jsonSchema } = await murmurly.eventTypes.getSchema(eventTypes[0].slug)
+
+const result = await murmurly.engagements.request(
+  {
+    name: 'Introductory Discovery Call',
+    email: 'client@example.com',
+    firstName: 'Jane',
+    lastName: 'Doe',
+    eventType: eventTypes[0].slug,
+    startDate: '2026-10-20'
+  },
+  { idempotencyKey: crypto.randomUUID() }
+)
+```
+
+## AI Agent Integration Guidance
+1. **Live guide**: `await murmurly.agentGuide()` (or `npx @murmurly/sdk guide`) returns Markdown written for this app: permissions, granted types, schemas and a tool definition. It never contains a secret.
+2. **Types**: `npx @murmurly/sdk codegen` writes `murmurly.d.ts` with exact payload interfaces.
+3. **Browser origin**: a public app only answers the origins set on it in Murmurly (e.g. `https://my-site.lovable.app`, `http://localhost:5173`). A `403` naming the origin means it must be added there.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@murmurly/sdk",
+  "version": "0.3.0",
+  "description": "Official TypeScript & JavaScript SDK for the Murmurly Public Ingestion API",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MurmurlyIO/platform.git",
+    "directory": "packages/sdk"
+  },
+  "bin": {
+    "murmurly": "./bin/murmurly.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "CHANGELOG.md",
+    "llms.txt",
+    "AI_GUIDE.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "vitest": "catalog:"
+  }
+}