Lex agent

The Lex agent adapter is the recommended way to interact with HappyView from JavaScript. It creates an @atproto/lex Agent from a HappyViewSession, so you can use @atproto/lex’s type-safe Client to make XRPC calls with HappyView’s DPoP authentication. All requests are routed to your HappyView instance. HappyView handles its own lexicons locally and passes any other method, such as com.atproto.repo.createRecord, to its XRPC proxy. The proxy forwards it to the user’s PDS as the user only when the instance’s proxy routing is serviceproxy.

The adapter gives you lexicon-level type checking on parameters, input bodies, and responses, and works with any library or tool that accepts an @atproto/lex Agent.

Installation

npm install @happyview/lex-agent @atproto/lex

@atproto/lex is a peer dependency (>=0.0.20).

Usage

import { Client } from "@atproto/lex";
import { HappyViewBrowserClient } from "@happyview/oauth-client-browser";
import { createAgent } from "@happyview/lex-agent";

const client = new HappyViewBrowserClient({
  instanceUrl: "https://happyview.example.com",
  clientId: "https://example.com/oauth-client-metadata.json",
  clientKey: "hvc_your_client_key",
});

// Restore an existing session
const result = await client.init();
const session = result?.session;
if (!session) throw new Error("Not signed in");

// Create a Lex agent from the session
const agent = createAgent(session);
const lex = new Client(agent);

Type-safe XRPC calls

With a Client instance, you can make type-safe XRPC calls using lexicon definitions:

// Query
const result = await lex.xrpc(myLexicons.com.example.getGame, {
  params: { slug: "celeste" },
});

// Procedure
await lex.xrpc(myLexicons.com.example.createPost, {
  input: { text: "Hello from HappyView!" },
});

The Client validates parameters and return types against the lexicon at the type level, so your IDE catches mismatches before runtime.

API

createAgent(session: HappyViewSession): Agent

Creates an @atproto/lex Agent from a HappyViewSession.

• agent.did: the session user’s DID
• agent.fetchHandler(path, init): delegates to session.fetchHandler, which attaches DPoP authentication headers and prepends the HappyView instance URL to relative paths