@synqauth/plugin-magic-link 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aerosol
+
+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

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @synqauth/plugin-magic-link
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Synq plugin for email codes and magic links from your own UI.
+
+Synq is customer identity for businesses: an OpenID Connect issuer for each of your brands, with Solana wallet, social, email and passkey sign-in. The documentation is at [docs.synq.build](https://docs.synq.build).
+
+This package is at 0.x and hasn't been published yet: its API can change in any release until Synq's first customer depends on it.
+
+## Usage
+
+Start an emailed code or magic link from your own UI: the person types their address on your page, and the brand's hosted page sends the email and takes the code or link. You bring no email transport.
+
+To take the code on your own page instead, with no trip to the hosted page, use own-UI sign-in: `useSignIn().emailCode` or `<SignInForm>` from `@synqauth/react`.
+
+```tsx
+import { magicLinkPlugin } from '@synqauth/plugin-magic-link'
+
+const { signInUrl } = magicLinkPlugin().actions(request)
+location.assign(signInUrl({ email: 'ada@example.com', returnTo: '/account' }))
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+//#region src/index.d.ts
+/** The plugin's id: its actions are under it in `usePlugin` and the mount's plugin list. */
+export declare const MAGIC_LINK_PLUGIN_ID = "magic-link";
+/** Calls the app's route mount, from its own page: what @synqauth/react and @synqauth/nextjs/client hand a plugin. */
+export type MountRequest = (path: string, init?: RequestInit) => Promise<Response>;
+/** What the magic-link plugin does from the page: where to send the person to get a code or link by email. */
+export interface MagicLinkActions {
+  /**
+   * Where to send someone to sign in with an emailed code or link: the
+   * brand's page at its email step, with `email` filled in when given.
+   */
+  signInUrl: (options?: {
+    email?: string;
+    returnTo?: string;
+  }) => string;
+}
+/** The magic-link plugin, in `SynqClientPlugin`'s shape: for `<SynqProvider plugins>` or `@synqauth/nextjs/client`. */
+export interface MagicLinkPlugin {
+  readonly id: typeof MAGIC_LINK_PLUGIN_ID;
+  actions: (request: MountRequest) => MagicLinkActions;
+}
+/** What `magicLinkPlugin()` takes. */
+export interface MagicLinkPluginOptions {
+  /** The route mount's path, as the app's `synqAuth()` has it: `/api/auth` by default. */
+  basePath?: string;
+}
+/** The magic-link plugin: the brand's email step, with the person's address filled in. */
+export declare function magicLinkPlugin(options?: MagicLinkPluginOptions): MagicLinkPlugin;
+//#endregion

package/dist/index.js

@@ -0,0 +1,24 @@
+//#region src/index.ts
+/** The plugin's id: its actions are under it in `usePlugin` and the mount's plugin list. */
+const MAGIC_LINK_PLUGIN_ID = "magic-link";
+/** A plausible address: something before and after one @, no spaces. The issuer checks it properly. */
+const EMAIL = /^[^\s@]+@[^\s@]+$/;
+/** The magic-link plugin: the brand's email step, with the person's address filled in. */
+function magicLinkPlugin(options = {}) {
+	const base = `/${(options.basePath ?? "/api/auth").replace(/^\/+|\/+$/g, "")}`;
+	return {
+		id: MAGIC_LINK_PLUGIN_ID,
+		actions: () => ({ signInUrl: ({ email, returnTo } = {}) => {
+			const query = new URLSearchParams({ method: "email" });
+			const address = email?.trim();
+			if (address) {
+				if (address.length > 254 || !EMAIL.test(address)) throw new TypeError(`Not an email address: ${address}`);
+				query.set("login_hint", address);
+			}
+			if (returnTo) query.set("returnTo", returnTo);
+			return `${base}/sign-in?${query.toString()}`;
+		} })
+	};
+}
+//#endregion
+export { MAGIC_LINK_PLUGIN_ID, magicLinkPlugin };

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@synqauth/plugin-magic-link",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "A Synq plugin that sends people from your own UI to the hosted page's emailed code or magic link.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aerosol-build/synq.git",
+    "directory": "packages/plugin-magic-link"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "vitest": "5.0.2"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc",
+    "test": "vitest run"
+  }
 }