nuxt-atproto 0.0.1

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 dxlliv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,271 @@
+# nuxt-atproto
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![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.
+
+## Overview
+
+`nuxt-atproto` is a Nuxt.js module that simplifies the OAuth authentication via AT Protocol.
+
+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.
+
+## 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
+
+Install the module via npm:
+
+```sh
+npm install nuxt-atproto
+```
+
+## Configuration
+
+Register the module in your `nuxt.config.js`:
+
+```ts
+export default defineNuxtConfig({
+    modules: ['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: '',
+                    client_name: '',
+                    client_uri: '',
+                    logo_uri: '',
+                    tos_uri: '',
+                    policy_uri: '',
+                    redirect_uris: [''],
+                    scope: 'atproto',
+                    grant_types: [],
+                    response_types: [],
+                    token_endpoint_auth_method: 'none',
+                    application_type: 'web',
+                    dpop_bound_access_tokens: true
+                }
+            },
+            signInOptions: {
+                state: '',
+                prompt: 'login',
+                scope: 'atproto',
+                ui_locales: 'en',
+            },
+        },
+        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
+<script setup lang="ts">
+const atproto = useAtproto()
+</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>
+    </template>
+</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 />
+
+### 🔢 agent
+
+Provides an object containing both a public `AtpAgent` for general access and an authenticated `Agent` to perform actions that require a logged-in user, such as posting, following, and liking.
+
+```ts
+const atproto = useAtproto()
+
+const profile = await atproto.agent.public.getProfile({actor: 'owdproject.org'})
+console.log(profile.data)
+
+const likedPost = await atproto.agent.account.likePost({cid, uri})
+console.log(likedPost.data)
+```
+
+**Parameters:**
+
+- `service` (optional): The base URL of the ATProto service.
+- `fetch` (optional): A custom fetch implementation.
+
+**Returns:** An object with both public AtpAgent or authenticated account Agent.
+
+<br />
+
+## License
+
+This package is released under the MIT license.
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/nuxt-atproto/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/nuxt-atproto
+
+[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-atproto.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/nuxt-atproto
+
+[license-src]: https://img.shields.io/npm/l/nuxt-atproto.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/nuxt-atproto
+
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,56 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { HookResult } from '@nuxt/schema';
+
+declare module '#app' {
+  interface RuntimeNuxtHooks {
+    'atproto:sessionCreated': (did: string) => HookResult
+    'atproto:sessionRestored': (did: string) => HookResult
+    'atproto:sessionDeleted': (did: string) => HookResult
+  }
+}
+
+declare module 'nuxt/schema' {
+  interface PublicRuntimeConfig {
+    atproto: AtprotoNuxtOptions
+  }
+}
+
+interface AtprotoNuxtOptions {
+  serviceEndpoint: {
+    private: string
+    public: string
+  }
+  oauth: {
+    clientMetadata: {
+      remote?: string
+      local?: {
+        client_id: string
+        client_name: string
+        client_uri: string
+        logo_uri: string
+        tos_uri: string
+        policy_uri: string
+        redirect_uris: [string, ...string[]]
+        scope: string
+        grant_types: Array<any>
+        response_types: Array<any>
+        token_endpoint_auth_method: string
+        application_type: string
+        dpop_bound_access_tokens: boolean
+      }
+    }
+    signInOptions: AtprotoSignInOptions
+  }
+  debug: boolean
+}
+
+interface AtprotoSignInOptions {
+  state: string
+  prompt: 'login' | 'consent'
+  scope: string
+  ui_locales: string
+}
+
+declare const _default: _nuxt_schema.NuxtModule<AtprotoNuxtOptions, AtprotoNuxtOptions, false>;
+
+export { _default as default };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "nuxt-atproto",
+  "configKey": "atproto",
+  "version": "0.0.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.1",
+    "unbuild": "3.5.0"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,76 @@
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { defineNuxtModule, createResolver, addImportsDir, addPlugin } from '@nuxt/kit';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "nuxt-atproto",
+    configKey: "atproto"
+  },
+  defaults: {
+    serviceEndpoint: {
+      private: "https://bsky.social",
+      public: "https://public.api.bsky.app"
+    },
+    oauth: {
+      clientMetadata: {
+        // load the client_metadata.json asynchronously from the URL
+        remote: "",
+        // or use the local client_metadata.json generated by `nuxt-atproto`
+        local: {
+          client_id: "",
+          client_name: "",
+          client_uri: "",
+          logo_uri: "",
+          tos_uri: "",
+          policy_uri: "",
+          redirect_uris: [""],
+          scope: "atproto",
+          grant_types: [],
+          response_types: [],
+          token_endpoint_auth_method: "none",
+          application_type: "web",
+          dpop_bound_access_tokens: true
+        }
+      },
+      signInOptions: {
+        state: "",
+        prompt: "login",
+        scope: "atproto",
+        ui_locales: "en"
+      }
+    },
+    debug: true
+  },
+  setup(_options, _nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    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");
+    });
+    if (!_options.oauth.clientMetadata.remote) {
+      try {
+        mkdirSync(publicDir, { recursive: true });
+      } catch (error) {
+        console.error("Failed creating /public/client-metadata.json", error);
+        return;
+      }
+      writeFileSync(
+        publicDir + "/client-metadata.json",
+        JSON.stringify(_options.oauth.clientMetadata.local, null, 2)
+      );
+    } else {
+      rmSync(publicDir + "/client-metadata.json");
+    }
+    addImportsDir(resolve("./runtime/composables"));
+    addPlugin(resolve("./runtime/plugin.client"));
+  }
+});
+
+export { module as default };

package/dist/runtime/composables/useAtproto.js

@@ -0,0 +1,74 @@
+import { Agent, AtpAgent } from "@atproto/api";
+import { useRuntimeConfig, useNuxtApp } from "nuxt/app";
+import { reactive } from "vue";
+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 useAgent(service2, fetch2) {
+    const { $atproto } = useNuxtApp();
+    const runtimeConfig2 = useRuntimeConfig();
+    if (!service2) {
+      service2 = runtimeConfig2.public.atproto.serviceEndpoint.public;
+    }
+    let accountAgent;
+    if ($atproto && $atproto.session.value) {
+      accountAgent = new Agent($atproto.session.value);
+    }
+    return reactive({
+      public: new AtpAgent({ service: service2, fetch: fetch2 }),
+      account: accountAgent
+    });
+  }
+  const agent = useAgent(service, fetch);
+  return {
+    signIn,
+    signInWithHandle,
+    signOut,
+    restore,
+    agent
+  };
+}

package/dist/runtime/plugin.client.d.ts

@@ -0,0 +1,12 @@
+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.client.js

@@ -0,0 +1,61 @@
+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/types.d.mts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.mjs'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.mjs'

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "nuxt-atproto",
+  "version": "0.0.1",
+  "description": "Interact with AT Protocol and Bluesky in your Nuxt.js application",
+  "keywords": [
+    "nuxt",
+    "bluesky",
+    "atprotocol",
+    "oauth",
+    "atproto",
+    "authentication"
+  ],
+  "license": "MIT",
+  "repository": "nuxt-atproto",
+  "homepage": "https://github.com/dxlliv/nuxt-atproto",
+  "author": {
+    "name": "dxlliv",
+    "url": "https://github.com/dxlliv"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "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"
+  },
+  "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",
+    "@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"
+  },
+  "unbuild": {
+    "failOnWarn": false
+  }
+}