pcp-protocol

PCP (Personal Context Protocol) Client Library

Typed JavaScript/TypeScript client for interacting with the PCP browser extension from React, Next.js, and standard web applications.

• 📦 Distributed as an npm package (pcp)
• ⚛️ Includes a React hook (usePCP) for effortless integration
• 🌐 Works in any browser environment with the PCP extension installed
• 🔄 Automatically refreshes links and handles token expiry

Installation

npm install pcp
# or
pnpm add pcp
# or
yarn add pcp

Note: Make sure the PCP browser extension is installed and the user is signed in.

Usage

React / Next.js

import { usePCP } from "pcp";

export default function ContextPanel() {
  const { status, loading, error, requestAccess, fetchData } = usePCP();

  return (
    <div>
      <button onClick={requestAccess} disabled={loading}>
        {status.connected ? "Re-request Access" : "Request PCP Access"}
      </button>

      <button onClick={() => fetchData().then(console.log)} disabled={!status.connected || loading}>
        Fetch Context Data
      </button>

      {error && <p style={{ color: "red" }}>{error.message}</p>}
      {status.connected && <p>Link expires at: {new Date(status.link!.expires_at).toLocaleString()}</p>}
    </div>
  );
}

Using in Next.js (avoiding SSR)

If you render PCP-dependent UI on the server, guard for the browser:

import dynamic from "next/dynamic";

const SafeContextPanel = dynamic(() => import("../components/ContextPanel"), {
  ssr: false,
});

export default function Page() {
  return <SafeContextPanel />;
}

Plain Browser (vanilla JS)

<script type="module">
  import { requestAccess, fetchData } from "https://cdn.skypack.dev/pcp";

  async function start() {
    try {
      const link = await requestAccess();
      console.log("Access granted", link);

      const data = await fetchData();
      console.log("Context data", data);
    } catch (error) {
      console.error("PCP error", error);
    }
  }

  start();
</script>

API Reference

Core Functions

import {
  requestAccess,
  getStatus,
  fetchData,
  getCurrentLink,
  isConnected,
  ensureConnected,
} from "pcp";

• requestAccess(): Promise<PCPLink> – Opens the extension prompt and returns the issued link
• getStatus(): Promise<PCPStatus> – Current connection state
• fetchData<T = unknown>(): Promise<T> – Fetches user context data from Supabase
• getCurrentLink(): PCPLink | null – Cached link (if available)
• isConnected(): boolean – Synchronous connection check
• ensureConnected(): Promise<PCPLink> – Makes sure a valid link exists, requesting one if necessary

React Hook

import { usePCP } from "pcp";

const {
  status,
  loading,
  error,
  requestAccess,
  fetchData,
  ensureConnected,
  isConnected,
  currentLink,
} = usePCP({ autoConnect: true, refreshIntervalMs: 5000 });

• status – { connected: boolean; link: PCPLink | null }
• loading – Indicates in-flight operations
• error – Last error encountered (if any)
• requestAccess() – Prompts the extension
• fetchData() – Fetches context data
• ensureConnected() – Ensures a valid link is present
• isConnected / currentLink – Derived convenience values

Publishing the Package

• Build the package

  pnpm install   # or npm install
  pnpm build     # outputs to dist/
  

• Test locally (optional)

  pnpm link --global
  # In your app
  pnpm link --global pcp
  

• Publish to npm

  npm publish --access public
  

Ensure the package.json fields (name, version, author, etc.) are correct before publishing.

Requirements

• PCP browser extension installed and the user authenticated
• Browser environment (the extension injects APIs into window)
• React 17+ when using the usePCP hook

File Structure

library/
  package.json
  tsconfig.json
  src/
    core.ts       # Core logic (no React)
    usePCP.ts     # React hook
    index.ts      # Public exports

License

MIT – free for commercial and personal use.