arcy.js 0.0.2 → 0.1.0

package/README.md

@@ -1,7 +1,98 @@
 # arcy.js
 
-The universal JavaScript utility for [ARCY](https://arcyai.com) — embed an AI agent that talks to, learns from, and acts on behalf of your users, in any web app regardless of framework.
+Embed an [ARCY](https://arcyai.com) AI agent in any web app. The agent talks to your users, learns what they are trying to do, and acts on their behalf.
 
-**This package is not yet released.** This name is reserved ahead of launch. Watch [arcyai.com](https://arcyai.com) for availability.
+No framework required. arcy.js is plain JavaScript that runs on any page, and it ships its own TypeScript types.
 
-In the meantime, see [`@arcyai/sdk`](https://www.npmjs.com/package/@arcyai/sdk) for the current framework-based SDK.
+> BETA. The API below is frozen, but the product around it is still moving. Report anything broken at [arcyai.com](https://arcyai.com).
+
+## Install
+
+```bash
+npm install arcy.js
+```
+
+Also works with `pnpm add arcy.js`, `bun add arcy.js`, and `yarn add arcy.js`.
+
+There is no separate types package. Types are bundled, so `@types/arcy.js` does not exist and you do not need it.
+
+## Use it
+
+Two calls, once, where your app starts. `init()` connects your environment. `identify()` says who the current user is.
+
+```ts
+import arcy from "arcy.js"
+
+arcy.init("YOUR_ENVIRONMENT_TOKEN")
+
+arcy.identify(user.id, {
+  user_first_name: user.firstName,
+  user_email: user.email,
+  user_signed_up_at: user.createdAt,
+})
+```
+
+Your environment token, with the real value already filled in, is in the dashboard under **Settings > Installation**.
+
+arcy.js runs in the browser only. In Next.js, React Router, Nuxt, or any framework that renders on the server, keep both calls inside a client component or a mount effect.
+
+### Without a bundler
+
+Paste two script tags before `</body>`. Nothing to install.
+
+```html
+<script src="https://cdn.arcyai.com/arcy.loader.js"></script>
+<script>
+  arcy.init("YOUR_ENVIRONMENT_TOKEN")
+  arcy.identify("USER_ID", {
+    user_first_name: "USER_FIRST_NAME",
+    user_email: "USER_EMAIL",
+  })
+</script>
+```
+
+## API
+
+| Method | What it does |
+| --- | --- |
+| `init(token, options?)` | Starts ARCY with your environment token. |
+| `identify(userId, attributes?, options?)` | Names the signed-in user and sends their attributes. |
+| `identifyAnonymous(attributes?)` | Same, for a user who has not signed in. |
+| `updateUser(attributes?)` | Sends new attribute values for the current user. |
+| `reset()` | Clears the session. Call it on sign-out. |
+| `open()` / `close()` | Opens or closes the chat panel. |
+| `on(event, handler)` | Listens for `"ready"`, `"open"`, or `"close"`. Returns an unsubscribe function. |
+| `VERSION` | The version of arcy.js on the page. |
+
+Nothing here throws, and no promise it returns rejects. A failure resolves and reports through a console warning, so ARCY can never take your page down.
+
+Attribute values may be a string, number, boolean, string array, or `null`. Passing `null` clears the key.
+
+### Options for `init()`
+
+| Option | What it does |
+| --- | --- |
+| `telemetry` | Consent signal for behavioral telemetry. Wire this to your cookie banner. |
+| `locale` | The reply language of the agent, as a two-letter code (`"en"`, `"tr"`). |
+| `contentLocale` | The user's content locale, region qualified (`"en-US"`, `"tr-TR"`). |
+| `defaultOpen` | Opens the panel on arrival. |
+
+Everything else ARCY does is configured in the dashboard, not in code. There is no config file, no build step, and nothing to redeploy when you change a setting.
+
+### Identity verification
+
+Pass a `userHash` to prove the user is who your app says they are:
+
+```ts
+arcy.identify(user.id, attributes, { userHash })
+```
+
+`userHash` is `HMAC-SHA256(environment secret, userId)`, computed on your server. Never compute it in the browser.
+
+## Docs
+
+Full setup guides per framework, auth provider snippets, and troubleshooting: [docs.arcyai.com](https://docs.arcyai.com)
+
+## License
+
+MIT