@arcyai/sdk

v0.1.73

Published

16 days ago

ARCY SDK — deploy an AI agent that your users can talk to, learn from, and put on autopilot

0High
0Medium
0Low

@arcyai/sdk

An agentic layer for your SaaS. Your users can ask questions, follow guided flows, and let ARCY operate your product for them.

ARCY embeds directly into your app as a persistent widget. Users open it to get answers in Chat mode, walk through step-by-step tutorials in Teach mode, or hand the wheel to the Agent and watch it navigate, click, and fill forms on their behalf. You get a behavioral analytics layer that maps every signal back to your product strategy.

Before you start

Get your keys from sdk.arcyai.com > Apps > [your app] > Keys

ARCY uses two environments. Each app has a separate key pair for each:

| Environment | Publishable key | Behavior | | ----------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Development | pk_test_... | Renders an ARCY Dev badge in the bottom-left corner so you can tell at a glance that you are running in test mode. Events are tracked but isolated from production data. | | Production | pk_live_... | No badge. Full production tracking. |

Add the keys for each environment to the corresponding .env file:

# .env.local (development)
NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY=pk_test_...
ARCY_SECRET_KEY=sk_test_...

# .env.production
NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY=pk_live_...
ARCY_SECRET_KEY=sk_live_...

NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY is safe to expose in client code. ARCY_SECRET_KEY is server-side only and must never appear in the browser.

Setup

Option 1: Automated (recommended)

Install the CLI globally once:

npm install -g @arcyai/sdk

Run init. It scans your codebase, detects your auth framework, adds data-arcy anchors to all interactive elements, generates ARCY.md and arcy.config.ts, and wires up ARCYProvider automatically.

arcy init

Takes 2-15 minutes depending on codebase size. The CLI reads your source files, maps your UI to ARCY anchors, and configures the provider for your auth setup (Clerk, NextAuth, Supabase, Firebase, or custom). Go get a coffee.

Push your config and go live:

arcy push

Confirm everything is connected:

arcy status --wait

--wait polls until the first real session is received, then prints confirmation and exits. No dashboard visit needed.

Reload your app. The ARCY panel appears in the bottom-right corner. Chat, Teach, and Agent modes are live.

Option 2: Manual

If you prefer to wire things up yourself or want to understand what the CLI does:

1. Install the package

npm install @arcyai/sdk
# or
pnpm add @arcyai/sdk
# or
yarn add @arcyai/sdk

2. Import the base styles

// In your root layout or global CSS entry point
import "@arcyai/sdk/styles"

3. Wrap your app with ARCYProvider

Pick the snippet for your auth framework:

Next.js + Clerk

// components/arcy-wrapper.tsx
"use client"
import { useUser } from "@clerk/nextjs"
import { ARCYProvider } from "@arcyai/sdk/react"

export function ArcyWrapper({ children }: { children: React.ReactNode }) {
  const { user, isLoaded } = useUser()

  if (!isLoaded || !user) return <>{children}</>

  return (
    <ARCYProvider
      publicKey={process.env.NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY!}
      userId={user.id}
      userTraits={{
        email: user.primaryEmailAddress?.emailAddress,
        name: user.fullName ?? undefined,
        plan: user.publicMetadata?.plan as string | undefined,
        createdAt: user.createdAt ?? undefined,
      }}
      organizationId={user.organizationMemberships?.[0]?.organization?.id}
      organizationTraits={{
        name: user.organizationMemberships?.[0]?.organization?.name ?? undefined,
      }}
    >
      {children}
    </ARCYProvider>
  )
}

// app/layout.tsx
import { ArcyWrapper } from "@/components/arcy-wrapper"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ArcyWrapper>{children}</ArcyWrapper>
      </body>
    </html>
  )
}

Next.js + NextAuth

// components/arcy-wrapper.tsx
"use client"
import { useSession } from "next-auth/react"
import { ARCYProvider } from "@arcyai/sdk/react"

export function ArcyWrapper({ children }: { children: React.ReactNode }) {
  const { data: session } = useSession()

  if (!session?.user) return <>{children}</>

  return (
    <ARCYProvider
      publicKey={process.env.NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY!}
      userId={session.user.id}
      userTraits={{
        email: session.user.email ?? undefined,
        name: session.user.name ?? undefined,
      }}
    >
      {children}
    </ARCYProvider>
  )
}

Next.js + Supabase

// components/arcy-wrapper.tsx
"use client"
import { useUser } from "@supabase/auth-helpers-react"
import { ARCYProvider } from "@arcyai/sdk/react"

export function ArcyWrapper({ children }: { children: React.ReactNode }) {
  const user = useUser()

  if (!user) return <>{children}</>

  return (
    <ARCYProvider
      publicKey={process.env.NEXT_PUBLIC_ARCY_PUBLISHABLE_KEY!}
      userId={user.id}
      userTraits={{
        email: user.email,
        createdAt: user.created_at,
        ...user.user_metadata,
      }}
    >
      {children}
    </ARCYProvider>
  )
}

React + Vite (custom auth)

// components/arcy-wrapper.tsx
import { ARCYProvider } from "@arcyai/sdk/react"

interface ArcyWrapperProps {
  children: React.ReactNode
  user: { id: string; email: string; name?: string; plan?: string } | null
}

export function ArcyWrapper({ children, user }: ArcyWrapperProps) {
  if (!user) return <>{children}</>

  return (
    <ARCYProvider
      publicKey={import.meta.env.VITE_ARCY_PUBLISHABLE_KEY}
      userId={user.id}
      userTraits={{
        email: user.email,
        name: user.name,
        plan: user.plan,
      }}
    >
      {children}
    </ARCYProvider>
  )
}

4. Mark interactive elements as anchors

Add data-arcy attributes to the UI elements you want ARCY to reference in guided flows and agent actions. The CLI does this automatically in Option 1.

<button data-arcy="invite-button">Invite member</button>
<nav data-arcy="main-nav">...</nav>
<section data-arcy="billing-settings">...</section>

5. Push config and go live

arcy push
arcy status --wait

The ARCY panel appears in the bottom-right corner of your app.

ARCYProvider props

| Prop | Type | Required | Description | | -------------------- | ----------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | publicKey | string | Yes | Your ARCY publishable key (pk_test_... or pk_live_...). Safe to expose in client code. Throws immediately if a secret key (sk_...) is passed. | | userId | string | No | Your user's ID from your auth provider. Enables per-user analytics and flow targeting. | | userTraits | UserTraits | No | User metadata: email, name, plan, role, createdAt. Expansion signals: seatCount, featureDepth, integrationCount. More signals means better product intelligence. | | organizationId | string | No | Organization ID for B2B products. Links users to accounts in the ARCY dashboard. | | organizationTraits | OrganizationTraits | No | Org-level metadata: name, plan. ICP fields: companySize, industry. Expansion signals: seatCount, integrationCount. | | navigationManifest | NavigationItem[] | No | Describes your app's pages so ARCY can answer "where is X?" questions and show redirect buttons in Chat mode. | | metadata | Record<string, string \| number \| boolean \| null> | No | Arbitrary session metadata attached to every event. |

Expansion signal fields

Pass these via organizationTraits to unlock ICP segmentation and expansion scoring in your ARCY dashboard.

<ARCYProvider
  publicKey="pk_..."
  userId={userId}
  organizationId={org.id}
  organizationTraits={{
    name: org.name,
    plan: org.plan,
    companySize: "51-200",   // "1-10" | "11-50" | "51-200" | "201-500" | "500+"
    industry: "FinTech",
    seatCount: org.seatCount,
    integrationCount: org.integrationCount,
  }}
  userTraits={{
    email: user.email,
    plan: user.plan,
    seatCount: user.seatCount,
    featureDepth: ["agent", "teach", "billing"],  // features this user actively uses
    integrationCount: user.integrationCount,
  }}
>
  {children}
</ARCYProvider>

companySize and industry are required for ICP segmentation. seatCount and integrationCount power expansion scoring. featureDepth tracks which product areas a user engages with.

CLI reference

ARCY CLI follows git naming conventions.

| Command | What it does | | -------------------- | ------------------------------------------------------------------------------------------------ | | arcy init | First-time setup: full codebase scan, auth detection, ARCYProvider wiring, data-arcy anchors | | arcy sync | Rescan after code changes: update anchors, ARCY.md, arcy.config.ts | | arcy push | Push local config to the ARCY backend | | arcy pull | Pull latest flows and config from the ARCY backend | | arcy status | Show connectivity and sync state | | arcy status --wait | Poll until the first session is received, then confirm and exit | | arcy log | Show push history | | arcy rm | Remove ARCY setup from your codebase |

Standard workflow after shipping new features:

arcy sync    # detect new/deleted elements, update ARCY.md and arcy.config.ts
arcy push    # push changes to ARCY backend
arcy status  # confirm everything is live

To pull flows edited in the ARCY dashboard:

arcy pull

Security and privacy

What leaves your environment:

arcy init scans your source files (.ts, .tsx, .js, .jsx) and sends file contents to ARCY for anchor analysis and flow generation. Config files (.env, *.pem, *.key, *.p12) are always excluded. The file count is printed before anything is sent.
ARCYProvider at runtime sends session metadata (the userId, userTraits, and organizationId you pass), route paths, and data-arcy anchor IDs when users interact with marked elements. No full DOM content, no user-typed text outside the ARCY chat panel, no cookies.
When a user sends a message in the ARCY panel, the message text and session context are sent to the ARCY backend for the agent response.

What never leaves your environment:

ARCY_SECRET_KEY (sk_...) is server-side only. ARCYProvider throws immediately if a secret key is detected in a browser context.
Source file contents after arcy init completes. Scanning is a one-time operation.
Any field not explicitly passed as a prop to ARCYProvider.
Cookie values or localStorage contents beyond the ARCY visitor ID and theme preference.

Storage used by the SDK:

localStorage: a persistent anonymous visitor ID (__arcy_vid) that links pre-signup behavior to identified users. Scoped to the host origin.
localStorage: ARCY theme preference (arcy-theme). Not sent to the backend.
sessionStorage: conversation state (chat messages, agent plan, teach session). Cleared when the tab closes.

Content Security Policy:

Add the following directive to allow ARCY network calls:

Content-Security-Policy: connect-src https://api.arcyai.com;

Staying in sync after code changes

When you ship new features or redesign existing screens:

arcy sync   # detects new/deleted elements, updates ARCY.md and arcy.config.ts
arcy push   # pushes changes to the ARCY backend

arcy sync is safe to run at any time. Pass --dry-run to preview changes before writing any files.

What ARCY is not

Not an analytics SDK. ARCY collects behavioral signals as a side effect of the agent layer, not as its primary purpose.
Not a tooltip library. ARCY uses your existing UI to answer questions and execute actions in it.
Not a chatbot. Agent mode navigates pages, clicks buttons, and fills forms on behalf of your user.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@arcyai/sdk

Before you start

Setup

Option 1: Automated (recommended)

Option 2: Manual

ARCYProvider props

Expansion signal fields

CLI reference

Security and privacy

Staying in sync after code changes

What ARCY is not

License