nuxt-atproto 0.0.5 → 0.1.0

package/README.md

@@ -5,288 +5,92 @@
 [![License][license-src]][license-href]
 [![Nuxt][nuxt-src]][nuxt-href]
 
-> Easily integrate [Bluesky](https://bsky.app) login and [AT Protocol](https://atproto.com/) authentication into your
-Nuxt.js app.
+> OAuth login and session management for [Bluesky](https://bsky.app) and [AT Protocol](https://atproto.com) in [Nuxt](https://nuxt.com).
 
-## Overview
+## Documentation
 
-`nuxt-atproto` is a Nuxt.js module that simplifies the OAuth authentication via AT Protocol.
+**[Documentation](https://dxlliv.github.io/nuxt-atproto/)** — getting started, guides, and API reference.
 
-It handles the login and the session management using the  `@atproto/oauth-client` library,  
-providing public and authenticated agents for seamless interaction with AT Protocol services.
+Run the docs site locally:
 
-## Features
-
-- SSR-friendly login via Bluesky and AT Protocol with automatic service endpoint resolution.
-- Allow logins without specifying the handle, enabling account selection from PDS interface.
-- Simple access to sign-in, sign-out, public and private agents from `useAtproto` composable.
-- Access to the underlying client and session with `$atproto` provided by the plugin.
-- Dynamically generates `client-metadata.json` when the Nuxt.js app starts.
-
-## Installation
+```bash
+cd docs && pnpm install && pnpm dev
+```
 
-Install the module via npm:
+Open **http://127.0.0.1:3456/nuxt-atproto/** (use `127.0.0.1`, not `localhost`, for the OAuth demo).
 
-```sh
-npm install nuxt-atproto
-```
+## Features
 
-## Configuration
+- AT Protocol OAuth in the browser (`@atproto/oauth-client-browser`)
+- Composables for session, auth, and cached `@atproto/api` agents
+- Lifecycle hooks: `atproto:sessionCreated`, `atproto:sessionRestored`, `atproto:sessionDeleted`
+- Typed `$atproto` plugin (`client`, `session`, `status`)
+- Optional generation of `public/client-metadata.json` from module config
 
-Register the module in your `nuxt.config.js`:
+## Quick start
 
-```ts
-export default defineNuxtConfig({
-    modules: ['nuxt-atproto']
-})
+```bash
+pnpm add nuxt-atproto
 ```
 
-You can configure `nuxt-atproto` in your `nuxt.config.ts` file under the `atproto` key.  
-The following options are available with their default values:
-
 ```ts
-defineNuxtConfig({
-    modules: ['nuxt-atproto'],
-    atproto: {
-        serviceEndpoint: {
-            private: 'https://bsky.social',
-            public: 'https://public.api.bsky.app'
-        },
-        oauth: {
-            clientMetadata: {
-                // url of your remote client_metadata.json, leave the field empty
-                // to let `nuxt-atproto` generate a local /public/client_metadata.json
-                remote: '',
-                // configuration for the local client_metadata.json
-                local: {
-                    client_id: 'https://nuxt-atproto.pages.dev/client-metadata.json',
-                    client_name: 'nuxt-atproto',
-                    client_uri: 'https://nuxt-atproto.pages.dev',
-                    logo_uri: 'https://nuxt-atproto.pages.dev/logo.png',
-                    tos_uri: 'https://nuxt-atproto.pages.dev',
-                    policy_uri: 'https://nuxt-atproto.pages.dev',
-                    redirect_uris: ['https://nuxt-atproto.pages.dev'],
-                    scope: "atproto transition:generic",
-                    grant_types: ["authorization_code", "refresh_token"],
-                    response_types: ["code"],
-                    token_endpoint_auth_method: 'none',
-                    application_type: 'web',
-                    dpop_bound_access_tokens: true
-                }
-            },
-            signInOptions: {
-                state: '',
-                prompt: 'login',
-                scope: 'atproto',
-                ui_locales: 'en',
-            },
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-atproto'],
+  atproto: {
+    oauth: {
+      clientMetadata: {
+        local: {
+          client_id: 'https://your-app.example/client-metadata.json',
+          client_name: 'My App',
+          client_uri: 'https://your-app.example',
+          redirect_uris: ['https://your-app.example'],
+          // ... see docs for full metadata
         },
-        debug: true,
-    }
+      },
+    },
+  },
 })
 ```
 
-You must configure the `atproto.oauth.clientMetadata` with in your `nuxt.config.ts`,  
-especially `client_id` and `redirect_uris`, for the authentication flow to work correctly.
-
-If you don't provide a remote URL in the module options, when Nuxt.js starts it will create a  `client-metadata.json` in your `public` folder.
-Using a local `client-metadata.json` generally offers a faster user experience compared to fetching it from a remote URL.
-
-## Usage
-
-#### Basic example
-
-```html
+```vue
 <script setup lang="ts">
-const atproto = useAtproto()
+const { isLogged, session } = useAtprotoSession()
+const { signIn, signInWithHandle, signOut } = useAtprotoAuth()
 </script>
 
 <template>
-    <div>
-        <Button @click="atproto.signIn()">
-            Sign-in with ATProto
-        </Button><br />
-        <Button @click="atproto.signInWithHandle('dxlliv.bsky.social')">
-            Sign-in with ATProto using dxlliv.bsky.social
-        </Button><br />
-        <Button @click="atproto.signInWithHandle()">
-            Sign-in with ATProto using your handle (prompt)
-        </Button>
-        <Button @click="atproto.restore('did:plc:2pkidgvfnbxx7sq3shporxij')">
-            Restore dxlliv.bsky.social session
-        </Button>
-    </div>
-    <template v-if="atproto.agent.account">
-        <div>logged with: {{atproto.agent.account.assertDid}}</div>
-        <Button @click="atproto.signOut()">
-            Sign-out
-        </Button>
+  <ClientOnly>
+    <button v-if="!isLogged" type="button" @click="signIn()">Sign in</button>
+    <template v-else>
+      <p>{{ session?.sub }}</p>
+      <button type="button" @click="signOut()">Sign out</button>
     </template>
+  </ClientOnly>
 </template>
 ```
 
-<br />
-
-## 🧩 useAtproto(service?: string, fetch?: any)
-
-A composable provided by `nuxt-atproto` that offers methods for user authentication and session management, including authenticating, signing out and session restore.
-
-```html
-
-<script setup lang="ts">
-const atproto = useAtproto()
-</script>
-```
-
-**Parameters:**
-
-- `service` (optional): Override the service endpoint of the public agent.
-- `fetch` (optional): A custom fetch implementation.
-
-<br />
-
-### ➡️ signIn(serviceEndpoint?: string, options?: AtprotoSignInOptions)
-
-Initiates the standard ATProto sign-in flow redirecting the user for authentication.
-
-```html
-
-<Button @click="atproto.signIn()">
-    Sign-in with ATProto
-</Button>
-```
-
-**Parameters:**
-
-- `serviceEndpoint`: *(optional)* The specific ATProto service endpoint to use for sign-in.
-- `options`: *(optional)* Additional options to configure the sign-in process.
-
-```ts
-// options
-{
-    state: "",
-    prompt: "login",
-    scope: "atproto",
-    ui_locales: "en"
-}
-```
-
-**Returns:** A Promise that might not directly resolve due to the redirection to the ATProto service.
-
-<br />
-
-### ➡️ signInWithHandle(handle?: string, options?: AtprotoSignInOptions)
-
-Initiates the ATProto sign-in flow using the user's AT Protocol handle.  
-The user will be prompted to enter their handle on the ATProto service if you omit the handle.
-
-```html
-
-<Button @click="atproto.signInWithHandle()">
-    Sign-in with ATProto
-</Button>
-```
-
-**Parameters:**
-
-- `handle`: *(optional)* The AT Protocol handle of the user.
-- `options`: *(optional)* Additional options to configure the sign-in process.
-
-**Returns:** A Promise that might not directly resolve due to the redirection to the ATProto service.
-
-<br />
-
-### ➡️ restore(did: string)
-
-Restore the user account associated with the provided Decentralized Identifier (DID).
-
-```html
-
-<Button @click="atproto.restore('did:plc:2pkidgvfnbxx7sq3shporxij')">
-    Restore dxlliv.bsky.social
-</Button>
-```
-
-**Parameters:**
-
-- `handle`: *(optional)* The Decentralized Identifier (DID) of the account to be restored.
-
-**Returns:** A Promise that resolves when the restoration process is complete.
-
-<br />
-
-### ➡️ signOut()
-
-Logs out the currently authenticated user and clears the stored session data.
-
-```html
-
-<Button @click="atproto.signOut()">
-    Sign-out
-</Button>
-```
-
-**Returns:** A Promise that resolves when the restoration process is complete.
-
-<br />
-
-### ➡️ isLogged()
-
-Indicates whether the user is currently authenticated.
-
-```ts
-const atproto = useAtproto()
-
-if (!atproto.isLogged()) {
-  return console.log('User is not logged in')
-}
-
-console.log('User is authenticated')
-```
-
-**Returns**: Returns a boolean indicating whether the user is authenticated.
-
-<br />
-
-### ➡️ getSession()
-
-Retrieves the current session from the Nuxt application context.
-
 ```ts
-const atproto = useAtproto()
-
-if (atproto.isLogged()) {
-  const session = atproto.getSession()
-  
-  console.log('User is logged in', session.sub)
-}
+const agent = useAtprotoAgent('authenticated')
+await agent.getTimeline()
 ```
 
-**Returns**: Returns the current AT Protocol OAuth Browser session.
-
-<br />
-
-## 🧩 useAgent(service?: string, fetch?: any)
-
-A composable provided by `nuxt-atproto` that offers methods for user authentication and session management, including authenticating, signing out and session restore.
-
-```html
-
-<script setup lang="ts">
-const agent = useAgent('public')
-</script>
-```
+> **Client-only OAuth.** Wrap login UI in `<ClientOnly>` or disable SSR on auth routes.
+> See the [introduction](https://dxlliv.github.io/nuxt-atproto/getting-started/introduction) in the docs.
 
-**Parameters:**
+## Composables
 
-- `service` (optional): Choose between `public`, `private` or a custom service endpoint.
-- `fetch` (optional): A custom fetch implementation.
+| Composable | Purpose |
+|------------|---------|
+| `useAtprotoSession()` | `session`, `isLogged`, `status` |
+| `useAtprotoAuth()` | `signIn`, `signInWithHandle`, `signOut`, `restore` |
+| `useAtprotoAgent(scope)` | Cached `Agent` / `AtpAgent` (`authenticated`, `public`, or custom URL) |
 
-<br />
+`useAtproto()` and `useAgent()` are deprecated — see [Migration](https://dxlliv.github.io/nuxt-atproto/advanced/migration).
 
 ## License
 
-This package is released under the MIT license.
+Released under the [MIT License](./LICENSE).
 
 <!-- Badges -->
 [npm-version-src]: https://img.shields.io/npm/v/nuxt-atproto/latest.svg?style=flat&colorA=020420&colorB=00DC82

package/dist/module.d.mts

@@ -1,7 +1,21 @@
 import * as _nuxt_schema from '@nuxt/schema';
 import { HookResult } from '@nuxt/schema';
+import { BrowserOAuthClient, OAuthSession } from '@atproto/oauth-client-browser';
+import { Ref } from 'vue';
+
+type AtprotoSessionStatus = 'initializing' | 'ready' | 'anonymous' | 'authenticated'
+
+interface AtprotoContext {
+  client: BrowserOAuthClient
+  session: Ref<OAuthSession | undefined>
+  status: Ref<AtprotoSessionStatus>
+}
 
 declare module '#app' {
+  interface NuxtApp {
+    $atproto: AtprotoContext
+  }
+
   interface RuntimeNuxtHooks {
     'atproto:sessionCreated': (did: string) => HookResult
     'atproto:sessionRestored': (did: string) => HookResult
@@ -9,7 +23,17 @@ declare module '#app' {
   }
 }
 
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $atproto: AtprotoContext
+  }
+}
+
 declare module 'nuxt/schema' {
+  /**
+   * Copied to `runtimeConfig.public.atproto` at build time.
+   * OAuth client metadata and endpoints are exposed to the client bundle by design.
+   */
   interface PublicRuntimeConfig {
     atproto: AtprotoNuxtOptions
   }
@@ -21,6 +45,11 @@ interface AtprotoNuxtOptions {
     public: string
   }
   oauth: {
+    /**
+     * When true, writes `public/client-metadata.json` from `oauth.clientMetadata.local` during module setup.
+     * @default false
+     */
+    writeClientMetadata?: boolean
     clientMetadata: {
       remote?: string
       local?: {
@@ -32,8 +61,8 @@ interface AtprotoNuxtOptions {
         policy_uri: string
         redirect_uris: string[]
         scope: string
-        grant_types: Array<any>
-        response_types: Array<any>
+        grant_types: Array<string>
+        response_types: Array<string>
         token_endpoint_auth_method: string
         application_type: string
         dpop_bound_access_tokens: boolean

package/dist/module.json

@@ -1,9 +1,9 @@
 {
   "name": "nuxt-atproto",
   "configKey": "atproto",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "builder": {
-    "@nuxt/module-builder": "1.0.1",
-    "unbuild": "3.5.0"
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
   }
 }

package/dist/module.mjs

@@ -1,7 +1,7 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { defineNuxtModule, createResolver, addImportsDir, addPlugin } from '@nuxt/kit';
 
-const module = defineNuxtModule({
+const module$1 = defineNuxtModule({
   meta: {
     name: "nuxt-atproto",
     configKey: "atproto"
@@ -12,6 +12,7 @@ const module = defineNuxtModule({
       public: "https://public.api.bsky.app"
     },
     oauth: {
+      writeClientMetadata: false,
       clientMetadata: {
         // load the client_metadata.json asynchronously from the URL
         remote: "",
@@ -46,28 +47,71 @@ const module = defineNuxtModule({
     const publicDir = resolve(_nuxt.options.rootDir, "public");
     _nuxt.options.runtimeConfig.public.atproto = _options;
     _nuxt.options.build.transpile = _nuxt.options.build.transpile || [];
-    _nuxt.options.build.transpile.push("@atproto/oauth-client-browser");
-    _nuxt.options.build.transpile.push("@atproto/api");
-    _nuxt.hook("vite:extendConfig", (config) => {
-      config.optimizeDeps = config.optimizeDeps || {};
-      config.optimizeDeps.include = config.optimizeDeps.include || [];
-      config.optimizeDeps.include.push("@atproto/oauth-client-browser");
-      config.optimizeDeps.include.push("@atproto/api");
+    _nuxt.options.build.transpile.push(/@atproto\//);
+    _nuxt.hook("vite:extendConfig", (viteConfig) => {
+      const config = viteConfig;
+      config.optimizeDeps = {
+        ...config.optimizeDeps,
+        include: [
+          ...config.optimizeDeps?.include ?? [],
+          "@atproto/oauth-client-browser",
+          "@atproto/api",
+          "core-js"
+        ],
+        esbuildOptions: {
+          ...config.optimizeDeps?.esbuildOptions,
+          define: {
+            ...config.optimizeDeps?.esbuildOptions?.define,
+            global: "globalThis"
+          }
+        }
+      };
+      const existingOutput = config.build?.rollupOptions?.output;
+      const outputOptions = typeof existingOutput === "object" && !Array.isArray(existingOutput) ? existingOutput : {};
+      config.build = {
+        ...config.build,
+        commonjsOptions: {
+          ...config.build?.commonjsOptions,
+          transformMixedEsModules: true,
+          include: [
+            ...Array.isArray(config.build?.commonjsOptions?.include) ? config.build.commonjsOptions.include : [],
+            /node_modules\/core-js/,
+            /node_modules\/@atproto\//
+          ]
+        },
+        rollupOptions: {
+          ...config.build?.rollupOptions,
+          output: {
+            ...outputOptions,
+            // core-js (via @atproto/oauth-client) can leave bare `exports` refs in the client chunk
+            banner: 'var exports=typeof exports!=="undefined"?exports:{};var module=typeof module!=="undefined"?module:{exports};'
+          }
+        }
+      };
+      config.define = {
+        ...config.define,
+        "process.env": config.define?.["process.env"] ?? {},
+        "global": "globalThis"
+      };
     });
-    try {
-      mkdirSync(publicDir, { recursive: true });
-    } catch (error) {
-      console.error("Failed creating /public/client-metadata.json", error);
-      return;
+    addImportsDir(resolve("./runtime/app/composables"));
+    addImportsDir(resolve("./runtime/app/utils"));
+    addPlugin({
+      src: resolve("./runtime/app/plugins/atproto.client"),
+      mode: "client"
+    });
+    if (_options.oauth.writeClientMetadata) {
+      try {
+        mkdirSync(publicDir, { recursive: true });
+        writeFileSync(
+          `${publicDir}/client-metadata.json`,
+          JSON.stringify(_options.oauth.clientMetadata.local, null, 2)
+        );
+      } catch (error) {
+        console.warn("[nuxt-atproto] Failed to write public/client-metadata.json:", error);
+      }
     }
-    writeFileSync(
-      publicDir + "/client-metadata.json",
-      JSON.stringify(_options.oauth.clientMetadata.local, null, 2)
-    );
-    addImportsDir(resolve("./runtime/composables"));
-    addImportsDir(resolve("./runtime/utils"));
-    addPlugin(resolve("./runtime/plugin"));
   }
 });
 
-export { module as default };
+export { module$1 as default };

package/dist/runtime/app/composables/useAgent.d.ts

@@ -0,0 +1,7 @@
+import { Agent } from '@atproto/api';
+/**
+ * Returns a cached AT Protocol agent for the given scope.
+ *
+ * @deprecated Use `useAtprotoAgent` instead (`private` → `authenticated`).
+ */
+export declare function useAgent(service: 'private' | 'public' | (string & {}), fetch?: typeof globalThis.fetch): Agent;

package/dist/runtime/app/composables/useAgent.js

@@ -0,0 +1,59 @@
+import { useNuxtApp, useState } from "nuxt/app";
+import { useAtprotoRuntimeConfig } from "../utils/useAtprotoRuntimeConfig.js";
+import { Agent, AtpAgent } from "@atproto/api";
+import {
+  customAgentStateKey,
+  invalidateAtprotoPrivateAgent,
+  PRIVATE_AGENT_SESSION_KEY,
+  PRIVATE_AGENT_STATE_KEY,
+  publicAgentStateKey
+} from "../utils/agentCache.js";
+export function useAgent(service, fetch) {
+  const atprotoConfig = useAtprotoRuntimeConfig();
+  const { $atproto } = useNuxtApp();
+  switch (service) {
+    case "private": {
+      if (!$atproto.session.value) {
+        invalidateAtprotoPrivateAgent();
+        throw new Error("Not authenticated");
+      }
+      const sessionSub = $atproto.session.value.sub;
+      const cachedAgent = useState(PRIVATE_AGENT_STATE_KEY, () => null);
+      const cachedSessionSub = useState(PRIVATE_AGENT_SESSION_KEY, () => null);
+      if (cachedAgent.value && cachedSessionSub.value === sessionSub) {
+        return cachedAgent.value;
+      }
+      const agent = new Agent($atproto.session.value);
+      cachedAgent.value = agent;
+      cachedSessionSub.value = sessionSub;
+      return agent;
+    }
+    case "public": {
+      const endpoint = atprotoConfig.serviceEndpoint.public;
+      const cacheKey = publicAgentStateKey(endpoint);
+      const cachedAgent = useState(cacheKey, () => null);
+      if (cachedAgent.value) {
+        return cachedAgent.value;
+      }
+      const agent = new AtpAgent({
+        service: endpoint,
+        fetch
+      });
+      cachedAgent.value = agent;
+      return agent;
+    }
+    default: {
+      const cacheKey = customAgentStateKey(service);
+      const cachedAgent = useState(cacheKey, () => null);
+      if (cachedAgent.value) {
+        return cachedAgent.value;
+      }
+      const agent = new AtpAgent({
+        service,
+        fetch
+      });
+      cachedAgent.value = agent;
+      return agent;
+    }
+  }
+}

package/dist/runtime/app/composables/useAtproto.d.ts

@@ -0,0 +1,12 @@
+import type { OAuthSession } from '@atproto/oauth-client-browser';
+/**
+ * @deprecated Use `useAtprotoSession` and `useAtprotoAuth` instead.
+ */
+export declare function useAtproto(): {
+    signInWithHandle: (handle?: string, options?: Parameters<(handle: string, options?: import("../../../types/index.js").AtprotoSignInOptions) => Promise<void>>[1]) => Promise<void>;
+    isLogged: () => boolean;
+    getSession: () => OAuthSession | undefined;
+    signIn: (serviceEndpoint?: string, options?: import("../../../types/index.js").AtprotoSignInOptions) => Promise<void>;
+    signOut: () => Promise<void>;
+    restore: (did: string) => Promise<OAuthSession>;
+};

package/dist/runtime/app/composables/useAtproto.js

@@ -0,0 +1,21 @@
+import { useAtprotoAuth } from "./useAtprotoAuth.js";
+import { useAtprotoSession } from "./useAtprotoSession.js";
+export function useAtproto() {
+  const { session, isLogged } = useAtprotoSession();
+  const auth = useAtprotoAuth();
+  return {
+    ...auth,
+    signInWithHandle: async (handle, options) => {
+      if (!handle) {
+        const handlePrompt = window.prompt("Type your handle");
+        if (!handlePrompt) {
+          return;
+        }
+        return auth.signInWithHandle(handlePrompt, options);
+      }
+      return auth.signInWithHandle(handle, options);
+    },
+    isLogged: () => isLogged.value,
+    getSession: () => session.value
+  };
+}

package/dist/runtime/app/composables/useAtprotoAgent.d.ts

@@ -0,0 +1,10 @@
+import type { Agent, AtpAgent } from '@atproto/api';
+export type AtprotoAgentScope = 'authenticated' | 'public' | (string & {});
+/**
+ * Returns a cached AT Protocol agent for the given scope (client-only).
+ *
+ * - `authenticated` — OAuth session agent (formerly `private`)
+ * - `public` — unauthenticated public API agent
+ * - custom string — `AtpAgent` for a specific PDS/service URL
+ */
+export declare function useAtprotoAgent(scope: AtprotoAgentScope, fetch?: typeof globalThis.fetch): Agent | AtpAgent;

package/dist/runtime/app/composables/useAtprotoAgent.js

@@ -0,0 +1,8 @@
+import { useAgent } from "./useAgent.js";
+export function useAtprotoAgent(scope, fetch) {
+  if (import.meta.server) {
+    throw new Error("useAtprotoAgent is only available on the client");
+  }
+  const service = scope === "authenticated" ? "private" : scope;
+  return useAgent(service, fetch);
+}

package/dist/runtime/app/composables/useAtprotoAuth.d.ts

@@ -0,0 +1,12 @@
+import type { OAuthSession } from '@atproto/oauth-client-browser';
+import type { AtprotoSignInOptions } from '../../../types/index.js';
+export interface UseAtprotoAuthReturn {
+    signIn: (serviceEndpoint?: string, options?: AtprotoSignInOptions) => Promise<void>;
+    signInWithHandle: (handle: string, options?: AtprotoSignInOptions) => Promise<void>;
+    signOut: () => Promise<void>;
+    restore: (did: string) => Promise<OAuthSession>;
+}
+/**
+ * ATProto sign-in, sign-out, and session restore (client-only).
+ */
+export declare function useAtprotoAuth(): UseAtprotoAuthReturn;

package/dist/runtime/app/composables/useAtprotoAuth.js

@@ -0,0 +1,70 @@
+import { useNuxtApp } from "nuxt/app";
+import { applyAtprotoSession } from "../utils/sessionLifecycle.js";
+import { useAtprotoRuntimeConfig } from "../utils/useAtprotoRuntimeConfig.js";
+const serverAuthReturn = {
+  signIn: async () => {
+  },
+  signInWithHandle: async () => {
+  },
+  signOut: async () => {
+  },
+  restore: async () => {
+    throw new Error("useAtprotoAuth is only available on the client");
+  }
+};
+export function useAtprotoAuth() {
+  if (import.meta.server) {
+    return serverAuthReturn;
+  }
+  const atprotoConfig = useAtprotoRuntimeConfig();
+  async function signIn(serviceEndpoint = atprotoConfig.serviceEndpoint.private, options = atprotoConfig.oauth.signInOptions) {
+    const { $atproto } = useNuxtApp();
+    try {
+      await $atproto.client.signInRedirect(
+        serviceEndpoint,
+        {
+          ...options,
+          signal: new AbortController().signal
+        }
+      );
+    } catch (error) {
+      console.error("Error during sign-in:", error);
+    }
+  }
+  async function signInWithHandle(handle, options = atprotoConfig.oauth.signInOptions) {
+    const { $atproto } = useNuxtApp();
+    try {
+      const url = await $atproto.client.authorize(handle, options);
+      window.location.href = url.href;
+    } catch (error) {
+      console.error(`Error during sign-in for handle ${handle}:`, error);
+    }
+  }
+  async function restore(did) {
+    const nuxtApp = useNuxtApp();
+    const session = await nuxtApp.$atproto.client.restore(did);
+    applyAtprotoSession(nuxtApp, session, "account-switch");
+    return session;
+  }
+  async function signOut() {
+    const nuxtApp = useNuxtApp();
+    const session = nuxtApp.$atproto.session.value;
+    if (session) {
+      try {
+        await nuxtApp.$atproto.client.revoke(session.did);
+      } catch (error) {
+        console.error("Error revoking ATProto session:", error);
+      }
+    }
+    applyAtprotoSession(nuxtApp, void 0, "sign-out");
+    if (atprotoConfig.debug) {
+      console.log("User signed out");
+    }
+  }
+  return {
+    signIn,
+    signInWithHandle,
+    signOut,
+    restore
+  };
+}

package/dist/runtime/app/composables/useAtprotoSession.d.ts

@@ -0,0 +1,12 @@
+import type { OAuthSession } from '@atproto/oauth-client-browser';
+import type { AtprotoSessionStatus } from '../../../types/index.js';
+import { type ComputedRef, type Ref } from 'vue';
+export interface UseAtprotoSessionReturn {
+    session: Ref<OAuthSession | undefined>;
+    isLogged: ComputedRef<boolean>;
+    status: Ref<AtprotoSessionStatus>;
+}
+/**
+ * Reactive ATProto OAuth session state (client-only).
+ */
+export declare function useAtprotoSession(): UseAtprotoSessionReturn;

package/dist/runtime/app/composables/useAtprotoSession.js

@@ -0,0 +1,18 @@
+import { useNuxtApp } from "nuxt/app";
+import { computed, shallowRef } from "vue";
+const serverSessionReturn = {
+  session: shallowRef(void 0),
+  isLogged: computed(() => false),
+  status: shallowRef("anonymous")
+};
+export function useAtprotoSession() {
+  if (import.meta.server) {
+    return serverSessionReturn;
+  }
+  const { $atproto } = useNuxtApp();
+  return {
+    session: $atproto.session,
+    isLogged: computed(() => !!$atproto.session.value),
+    status: $atproto.status
+  };
+}

package/dist/runtime/app/plugins/atproto.client.d.ts

@@ -0,0 +1,7 @@
+import type { AtprotoContext } from '../../../types/index.js';
+declare const _default: import("nuxt/app").Plugin<{
+    atproto: AtprotoContext;
+}> & import("nuxt/app").ObjectPlugin<{
+    atproto: AtprotoContext;
+}>;
+export default _default;

package/dist/runtime/app/plugins/atproto.client.js

@@ -0,0 +1,68 @@
+import { BrowserOAuthClient } from "@atproto/oauth-client-browser";
+import { defineNuxtPlugin } from "nuxt/app";
+import { ref } from "vue";
+import { useAtprotoRuntimeConfig } from "../utils/useAtprotoRuntimeConfig.js";
+import { applyAtprotoSession } from "../utils/sessionLifecycle.js";
+export default defineNuxtPlugin({
+  name: "atproto",
+  async setup(nuxtApp) {
+    const atprotoConfig = useAtprotoRuntimeConfig();
+    const status = ref("initializing");
+    const atprotoOAuthSession = ref();
+    const clientOptions = {
+      handleResolver: atprotoConfig.serviceEndpoint.private,
+      onDelete: (sub, cause) => {
+        if (atprotoConfig.debug) {
+          console.warn(`Session deleted for ${sub}. Cause:`, cause);
+        }
+        nuxtApp.hooks.callHook("atproto:sessionDeleted", sub);
+      }
+    };
+    let atprotoOAuthClient;
+    if (atprotoConfig.oauth.clientMetadata.remote) {
+      atprotoOAuthClient = await BrowserOAuthClient.load({
+        ...clientOptions,
+        clientId: atprotoConfig.oauth.clientMetadata.remote
+      });
+    } else {
+      atprotoOAuthClient = new BrowserOAuthClient({
+        ...clientOptions,
+        ...import.meta.env.DEV || !atprotoConfig.oauth.clientMetadata.local ? {} : { clientMetadata: atprotoConfig.oauth.clientMetadata.local }
+      });
+    }
+    const atproto = {
+      client: atprotoOAuthClient,
+      session: atprotoOAuthSession,
+      status
+    };
+    try {
+      const result = await atprotoOAuthClient.init();
+      if (result) {
+        const { session, state } = result;
+        if (atprotoConfig.debug) {
+          if (state != null) {
+            console.log(`${session.sub} was successfully authenticated (state: ${state})`);
+          } else {
+            console.log(`${session.sub} was restored (last active session)`);
+          }
+        }
+        applyAtprotoSession(
+          nuxtApp,
+          session,
+          state != null ? "oauth-return" : "cold-restore",
+          { deferHooks: true, atproto }
+        );
+      } else {
+        status.value = "anonymous";
+      }
+    } catch (error) {
+      console.error("Error initializing ATProto client or restoring session:", error);
+      status.value = "anonymous";
+    }
+    return {
+      provide: {
+        atproto
+      }
+    };
+  }
+});

package/dist/runtime/app/utils/agentCache.d.ts

@@ -0,0 +1,8 @@
+export declare const PRIVATE_AGENT_STATE_KEY = "atproto:agent:private";
+export declare const PRIVATE_AGENT_SESSION_KEY = "atproto:agent:private-session-sub";
+export declare function publicAgentStateKey(serviceEndpoint: string): string;
+export declare function customAgentStateKey(service: string): string;
+/**
+ * Clears the cached authenticated agent. Call after sign-out or before restore.
+ */
+export declare function invalidateAtprotoPrivateAgent(): void;

package/dist/runtime/app/utils/agentCache.js

@@ -0,0 +1,15 @@
+import { useState } from "nuxt/app";
+export const PRIVATE_AGENT_STATE_KEY = "atproto:agent:private";
+export const PRIVATE_AGENT_SESSION_KEY = "atproto:agent:private-session-sub";
+export function publicAgentStateKey(serviceEndpoint) {
+  return `atproto:agent:public:${serviceEndpoint}`;
+}
+export function customAgentStateKey(service) {
+  return `atproto:agent:${service}`;
+}
+export function invalidateAtprotoPrivateAgent() {
+  const cachedAgent = useState(PRIVATE_AGENT_STATE_KEY, () => null);
+  const cachedSessionSub = useState(PRIVATE_AGENT_SESSION_KEY, () => null);
+  cachedAgent.value = null;
+  cachedSessionSub.value = null;
+}

package/dist/runtime/app/utils/sessionLifecycle.d.ts

@@ -0,0 +1,22 @@
+import type { OAuthSession } from '@atproto/oauth-client-browser';
+import type { NuxtApp } from 'nuxt/app';
+import type { AtprotoContext } from '../../../types/index.js';
+export interface AtprotoSessionLifecycleHooks {
+    hook: (name: string, callback: () => void) => void;
+    callHook: (name: string, did: string) => void | Promise<void>;
+}
+export type AtprotoSessionTransition = 'oauth-return' | 'cold-restore' | 'account-switch' | 'sign-out';
+export interface ApplyAtprotoSessionOptions {
+    /** When true, lifecycle hooks run after `app:mounted` (plugin init). */
+    deferHooks?: boolean;
+    /** Pass during plugin setup before `provide` returns. */
+    atproto?: AtprotoContext;
+}
+/**
+ * Updates `$atproto` session state, agent cache, status, and lifecycle hooks.
+ */
+export declare function applyAtprotoSession(nuxtApp: NuxtApp, session: OAuthSession | undefined, transition: AtprotoSessionTransition, options?: ApplyAtprotoSessionOptions): void;
+/**
+ * @deprecated Use `applyAtprotoSession` with `deferHooks: true` instead.
+ */
+export declare function scheduleAtprotoSessionHooks(hooks: AtprotoSessionLifecycleHooks, sessionSub: string, state: string | null | undefined): void;

package/dist/runtime/app/utils/sessionLifecycle.js

@@ -0,0 +1,29 @@
+import { invalidateAtprotoPrivateAgent } from "./agentCache.js";
+export function applyAtprotoSession(nuxtApp, session, transition, options = {}) {
+  const atproto = options.atproto ?? nuxtApp.$atproto;
+  const { deferHooks = false } = options;
+  if (session) {
+    invalidateAtprotoPrivateAgent();
+    atproto.session.value = session;
+    atproto.status.value = "authenticated";
+    const hookName = transition === "oauth-return" ? "atproto:sessionCreated" : "atproto:sessionRestored";
+    emitSessionLifecycleHook(nuxtApp.hooks, hookName, session.sub, deferHooks);
+    return;
+  }
+  invalidateAtprotoPrivateAgent();
+  atproto.session.value = void 0;
+  atproto.status.value = "anonymous";
+}
+function emitSessionLifecycleHook(hooks, hookName, did, defer) {
+  if (defer) {
+    hooks.hook("app:mounted", () => {
+      hooks.callHook(hookName, did);
+    });
+    return;
+  }
+  hooks.callHook(hookName, did);
+}
+export function scheduleAtprotoSessionHooks(hooks, sessionSub, state) {
+  const hookName = state != null ? "atproto:sessionCreated" : "atproto:sessionRestored";
+  emitSessionLifecycleHook(hooks, hookName, sessionSub, true);
+}

package/dist/runtime/app/utils/useAtprotoRuntimeConfig.d.ts

@@ -0,0 +1,2 @@
+import type { AtprotoNuxtOptions } from '../../../types/index.js';
+export declare function useAtprotoRuntimeConfig(): AtprotoNuxtOptions;

package/dist/runtime/app/utils/useAtprotoRuntimeConfig.js

@@ -0,0 +1,4 @@
+import { useRuntimeConfig } from "nuxt/app";
+export function useAtprotoRuntimeConfig() {
+  return useRuntimeConfig().public.atproto;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-atproto",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "description": "Interact with AT Protocol and Bluesky in your Nuxt.js application",
   "keywords": [
     "nuxt",
@@ -47,23 +47,23 @@
     "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
   },
   "dependencies": {
-    "@nuxt/kit": "^3.17.2",
-    "@atproto/api": "^0.15.3",
-    "@atproto/oauth-client-browser": "^0.3.11"
+    "@nuxt/kit": "^4.4.6",
+    "@atproto/api": "^0.20.6",
+    "@atproto/oauth-client-browser": "^0.4.1"
   },
   "devDependencies": {
-    "@nuxt/devtools": "^2.4.0",
-    "@nuxt/eslint-config": "^1.3.0",
-    "@nuxt/module-builder": "^1.0.1",
-    "@nuxt/schema": "^3.17.2",
-    "@nuxt/test-utils": "^3.18.0",
+    "@nuxt/devtools": "^3.2.4",
+    "@nuxt/eslint-config": "^1.15.2",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.4.6",
     "@types/node": "latest",
-    "changelogen": "^0.6.1",
-    "eslint": "^9.26.0",
-    "nuxt": "^3.17.2",
-    "typescript": "~5.8.3",
-    "vitest": "^3.1.2",
-    "vue-tsc": "^2.2.10"
+    "changelogen": "^0.6.2",
+    "eslint": "^10.4.0",
+    "nuxt": "^4.4.6",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.7",
+    "vue": "^3.5.35",
+    "vue-tsc": "^3.3.2"
   },
   "unbuild": {
     "failOnWarn": false

package/dist/runtime/composables/useAgent.d.ts

@@ -1,8 +0,0 @@
-import { Agent } from "@atproto/api";
-/**
- * Provide AT Protocol agent
- *
- * @param service
- * @param fetch
- */
-export declare function useAgent(service: string, fetch?: any): Agent;

package/dist/runtime/composables/useAgent.js

@@ -1,23 +0,0 @@
-import { useNuxtApp, useRuntimeConfig } from "#app";
-import { Agent, AtpAgent } from "@atproto/api";
-export function useAgent(service, fetch) {
-  const runtimeConfig = useRuntimeConfig();
-  const { $atproto } = useNuxtApp();
-  switch (service) {
-    case "private":
-      if (!$atproto.session.value) {
-        throw new Error("Not authenticated");
-      }
-      return new Agent($atproto.session.value);
-    case "public":
-      return new AtpAgent({
-        service: runtimeConfig.public.atproto.serviceEndpoint.public,
-        fetch
-      });
-    default:
-      return new AtpAgent({
-        service,
-        fetch
-      });
-  }
-}

package/dist/runtime/composables/useAtproto.d.ts

@@ -1,9 +0,0 @@
-import type { OAuthSession } from '@atproto/oauth-client';
-export declare function useAtproto(service?: string, fetch?: any): {
-    signIn: (serviceEndpoint?: string, options?: any) => Promise<void>;
-    signInWithHandle: (handle?: string, options?: any) => Promise<void>;
-    signOut: () => Promise<void>;
-    restore: (did: string) => Promise<OAuthSession>;
-    isLogged: () => boolean;
-    getSession: () => any;
-};

package/dist/runtime/composables/useAtproto.js

@@ -1,65 +0,0 @@
-import { useRuntimeConfig, useNuxtApp } from "nuxt/app";
-export function useAtproto(service, fetch) {
-  const runtimeConfig = useRuntimeConfig();
-  async function signIn(serviceEndpoint = runtimeConfig.public.atproto.serviceEndpoint.private, options = runtimeConfig.public.atproto.oauth.signInOptions) {
-    const { $atproto } = useNuxtApp();
-    try {
-      await $atproto.client.signInRedirect(
-        serviceEndpoint,
-        {
-          ...options,
-          signal: new AbortController().signal
-        }
-      );
-    } catch (error) {
-      console.error(`Error during sign-in:`, error);
-    }
-  }
-  async function signInWithHandle(handle, options = runtimeConfig.public.atproto.oauth.signInOptions) {
-    const { $atproto } = useNuxtApp();
-    try {
-      let handlePrompt = null;
-      if (!handle) {
-        handlePrompt = window.prompt("Type your handle");
-        if (!handlePrompt) {
-          return;
-        }
-        handle = handlePrompt;
-      }
-      const url = await $atproto.client.authorize(handle, options);
-      window.location.href = url.href;
-    } catch (error) {
-      console.error(`Error during sign-in for handle ${handle}:`, error);
-    }
-  }
-  async function restore(did) {
-    const { $atproto } = useNuxtApp();
-    const session = await $atproto.client.restore(did);
-    $atproto.session.value = session;
-    return session;
-  }
-  async function signOut() {
-    const { $atproto } = useNuxtApp();
-    $atproto.client.revoke($atproto.session.value.did);
-    $atproto.session.value = void 0;
-    if (runtimeConfig.public.atproto.debug) {
-      console.log("User signed out");
-    }
-  }
-  function isLogged() {
-    const { $atproto } = useNuxtApp();
-    return !!$atproto.session.value;
-  }
-  function getSession() {
-    const { $atproto } = useNuxtApp();
-    return $atproto.session.value;
-  }
-  return {
-    signIn,
-    signInWithHandle,
-    signOut,
-    restore,
-    isLogged,
-    getSession
-  };
-}

package/dist/runtime/plugin.d.ts

@@ -1,12 +0,0 @@
-declare const _default: import("nuxt/app").Plugin<{
-    atproto: {
-        client: any;
-        session: import("vue").Ref<any, any>;
-    };
-}> & import("nuxt/app").ObjectPlugin<{
-    atproto: {
-        client: any;
-        session: import("vue").Ref<any, any>;
-    };
-}>;
-export default _default;

package/dist/runtime/plugin.js

@@ -1,61 +0,0 @@
-import { BrowserOAuthClient } from "@atproto/oauth-client-browser";
-import { useRuntimeConfig, defineNuxtPlugin } from "nuxt/app";
-import { ref } from "vue";
-export default defineNuxtPlugin({
-  name: "atproto",
-  async setup(_nuxtApp) {
-    const runtimeConfig = useRuntimeConfig();
-    let atprotoOAuthClient;
-    const atprotoOAuthSession = ref();
-    if (runtimeConfig.public.atproto.oauth.clientMetadata.remote) {
-      atprotoOAuthClient = await BrowserOAuthClient.load({
-        handleResolver: runtimeConfig.public.atproto.serviceEndpoint.private,
-        clientId: runtimeConfig.public.atproto.oauth.clientMetadata.remote
-        // todo implement custom fetch
-      });
-    } else {
-      atprotoOAuthClient = new BrowserOAuthClient({
-        handleResolver: runtimeConfig.public.atproto.serviceEndpoint.private,
-        // @ts-ignore
-        clientMetadata: import.meta.env.MODE === "development" ? void 0 : runtimeConfig.public.atproto.oauth.clientMetadata.local
-        // todo implement custom fetch
-      });
-    }
-    atprotoOAuthClient.addEventListener("deleted", (event) => {
-      const { sub, cause } = event.detail;
-      if (runtimeConfig.public.atproto.debug) {
-        console.warn(`Session deleted for ${sub}. Cause:`, cause);
-      }
-      _nuxtApp.hooks.callHook("atproto:sessionDeleted", sub);
-    });
-    await atprotoOAuthClient.init().then(async (result) => {
-      if (result) {
-        const { session, state } = result;
-        if (runtimeConfig.public.atproto.debug) {
-          if (state != null) {
-            console.log(`${session.sub} was successfully authenticated (state: ${state})`);
-            _nuxtApp.hook("app:mounted", async () => {
-              _nuxtApp.hooks.callHook("atproto:sessionCreated", session.sub);
-            });
-          } else {
-            console.log(`${session.sub} was restored (last active session)`);
-            _nuxtApp.hook("app:mounted", async () => {
-              _nuxtApp.hooks.callHook("atproto:sessionRestored", session.sub);
-            });
-          }
-        }
-        atprotoOAuthSession.value = session;
-      }
-    }).catch((error) => {
-      console.error("Error initializing ATProto client or restoring session:", error);
-    });
-    return {
-      provide: {
-        atproto: {
-          client: atprotoOAuthClient,
-          session: atprotoOAuthSession
-        }
-      }
-    };
-  }
-});

package/dist/runtime/utils/utilActor.d.ts

@@ -1,2 +0,0 @@
-export declare function resolveActorDid(handle: string): Promise<string>;
-export declare function resolveActorServiceEndpoint(did: string): Promise<string>;

package/dist/runtime/utils/utilActor.js

@@ -1,16 +0,0 @@
-import { useAgent } from "../composables/useAgent.js";
-export async function resolveActorDid(handle) {
-  const agent = useAgent("public");
-  const { did } = await agent.com.atproto.identity.resolveHandle({
-    handle
-  }).then((result) => result.data);
-  return did;
-}
-export async function resolveActorServiceEndpoint(did) {
-  const response = await fetch(`https://plc.directory/${did}`);
-  if (!response.ok) {
-    throw new Error("Failed to fetch profile service endpoint");
-  }
-  const data = await response.json();
-  return data.service[0].serviceEndpoint;
-}