@synqauth/js 0.0.0-stage → 0.0.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,40 @@
-# Temporary Holding Version
+# @synqauth/js
 
-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.
+Synq's framework-agnostic client: sign-in and sessions in the browser, the account API, and token and webhook verification on your server.
+
+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.
+
+## The account API
+
+For an app that holds its own session, `createAccountClient` calls the brand's account API for the person signed in:
+
+```ts
+import { accountApiUrl, createAccountClient, createSynqClient, linkSignIn } from '@synqauth/js'
+
+const synq = createSynqClient({
+  issuer: 'https://acme.auth.synq.build',
+  clientId: 'app_…',
+  redirectUri: 'https://app.example.com/callback',
+  scope: 'openid offline_access me:read me:write',
+  resource: accountApiUrl('https://acme.auth.synq.build'),
+})
+const account = createAccountClient({
+  issuer: 'https://acme.auth.synq.build',
+  accessToken: () => synq.getAccessToken(),
+})
+
+const { data: me, error } = await account.me()
+await account.user.update({ name: 'Ada Lovelace' })
+
+// Adding a wallet: a link request, then a fresh sign-in that carries it.
+const { data: request } = await account.accounts.link('wallet')
+if (request) await synq.signIn(linkSignIn(request))
+```
+
+Every call answers `{ data, error }` and never throws for what Synq answers; branch on `error.code`.
+
+## License
+
+MIT

package/dist/api-Cf9K1Rc9.js

@@ -0,0 +1,163 @@
+import { AuthorizationResponseError, OperationProcessingError, ResponseBodyError, WWWAuthenticateChallengeError } from "oauth4webapi";
+//#region src/errors.ts
+/**
+* Every error the SDK throws. Branch on `code`, which is stable: the API's
+* problem `code`, OAuth's `error`, or one of the SDK's own; never on the
+* message.
+*/
+var SynqError = class extends Error {
+	name = "SynqError";
+	code;
+	/** The HTTP status Synq answered with, when it answered. */
+	status;
+	/** What Synq said about it: OAuth's `error_description` or a problem's `detail`. */
+	description;
+	/**
+	* How many seconds to wait before trying again, from Synq's `Retry-After`:
+	* set on `rate_limited` (429), and wherever else Synq sends one.
+	*/
+	retryAfter;
+	constructor(code, message, options = {}) {
+		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+		this.code = code;
+		this.status = options.status;
+		this.description = options.description;
+		this.retryAfter = options.retryAfter;
+	}
+};
+/** Whether `error` is a `SynqError`, with `code` when given. */
+function isSynqError(error, code) {
+	return error instanceof SynqError && (code === void 0 || error.code === code);
+}
+/** A `SynqError` for a problem document a Synq API answered with. */
+function problemError(status, problem, retryAfter) {
+	const code = typeof problem.code === "string" ? problem.code : `http_${status}`;
+	const description = typeof problem.detail === "string" ? problem.detail : void 0;
+	return new SynqError(code, description ?? problem.title ?? `Synq answered ${status}`, {
+		status,
+		description,
+		retryAfter,
+		cause: problem
+	});
+}
+/**
+* The seconds a `Retry-After` header asks for: a number of seconds, or an
+* HTTP date, counted from `now`. Undefined when there is none, or it can't
+* be read.
+*/
+function retryAfterSeconds(header, now = Date.now()) {
+	const value = header?.trim();
+	if (!value) return void 0;
+	if (/^[0-9]+$/.test(value)) return Number(value);
+	if (!/[A-Za-z]/.test(value)) return void 0;
+	const at = Date.parse(value);
+	return Number.isNaN(at) ? void 0 : Math.max(0, Math.ceil((at - now) / 1e3));
+}
+/**
+* A `SynqError` for whatever went wrong talking to Synq's issuer: OAuth's
+* error responses keep their `error`, a failed check of Synq's answer is
+* `invalid_response`, and a request that never got an answer is
+* `network_error`.
+*/
+function toSynqError(error) {
+	if (error instanceof SynqError) return error;
+	if (error instanceof ResponseBodyError) return new SynqError(error.error, error.error_description ?? error.error, {
+		status: error.status,
+		description: error.error_description,
+		cause: error
+	});
+	if (error instanceof AuthorizationResponseError) return new SynqError(error.error, error.error_description ?? error.error, {
+		description: error.error_description,
+		cause: error
+	});
+	if (error instanceof WWWAuthenticateChallengeError) {
+		const challenge = error.cause[0];
+		const code = challenge?.parameters.error ?? "invalid_token";
+		const description = challenge?.parameters.error_description;
+		return new SynqError(code, description ?? code, {
+			status: error.status,
+			description,
+			cause: error
+		});
+	}
+	if (error instanceof OperationProcessingError) return new SynqError("invalid_response", error.message, { cause: error });
+	if (error instanceof TypeError) return new SynqError("network_error", `Synq couldn't be reached: ${error.message}`, { cause: error });
+	return new SynqError("invalid_response", error instanceof Error ? error.message : "Synq answered with something unexpected", { cause: error });
+}
+//#endregion
+//#region src/urls.ts
+/** Whether a host is this machine: a Synq stack under `localhost`, or a loopback address. */
+function isLoopback(hostname) {
+	return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+/**
+* `value` as a URL, which must be https: Synq's hosts always are. Plain http
+* only on this machine, for a local Synq stack. `what` names it in the error.
+*/
+function secureUrl(value, what) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new SynqError("invalid_options", `${what} isn't a URL: ${String(value)}`);
+	}
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback(url.hostname))) throw new SynqError("invalid_options", `${what} must be https: (http: only for a Synq stack on this machine, under 'localhost')`);
+	return url;
+}
+//#endregion
+//#region src/api.ts
+function createApiClient(options) {
+	const base = secureUrl(options.baseUrl, "The API base URL").href.replace(/\/+$/, "");
+	const call = (method) => ((path, request = {}) => send(method, path, request));
+	async function send(method, path, request) {
+		const url = new URL(base + fill(path, request.path));
+		for (const [name, value] of Object.entries(request.query ?? {})) {
+			if (value === void 0) continue;
+			for (const item of Array.isArray(value) ? value : [value]) url.searchParams.append(name, String(item));
+		}
+		const headers = new Headers({
+			accept: "application/json, application/problem+json",
+			authorization: `Bearer ${await options.credential()}`
+		});
+		if (request.body !== void 0) headers.set("content-type", "application/json");
+		if (request.idempotencyKey) headers.set("idempotency-key", request.idempotencyKey);
+		let response;
+		try {
+			response = await (options.fetch ?? fetch)(url, {
+				method: method.toUpperCase(),
+				headers,
+				body: request.body === void 0 ? void 0 : JSON.stringify(request.body),
+				signal: request.signal
+			});
+		} catch (error) {
+			throw new SynqError("network_error", `Synq couldn't be reached: ${String(error)}`, { cause: error });
+		}
+		const text = await response.text();
+		let json;
+		try {
+			json = text ? JSON.parse(text) : void 0;
+		} catch {
+			json = void 0;
+		}
+		if (!response.ok) throw problemError(response.status, json !== null && typeof json === "object" ? json : {}, retryAfterSeconds(response.headers.get("retry-after")));
+		return json;
+	}
+	return {
+		get: call("get"),
+		post: call("post"),
+		put: call("put"),
+		patch: call("patch"),
+		delete: call("delete")
+	};
+}
+/** The path with each `{name}` replaced by its parameter, encoded. */
+function fill(path, params = {}) {
+	return path.replace(/\{([^}]+)\}/g, (_, name) => {
+		const value = params[name];
+		if (value === void 0 || value === "") throw new SynqError("invalid_options", `The path ${path} needs ${name}`);
+		if (/^\.+$/.test(String(value))) throw new SynqError("invalid_options", `${name} can't be ${String(value)}`);
+		return encodeURIComponent(String(value));
+	});
+}
+//#endregion
+export { problemError as a, isSynqError as i, secureUrl as n, toSynqError as o, SynqError as r, createApiClient as t };