@flung.dev/connect 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flung
+
+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,126 @@
-# Temporary Holding Version
+# @flung.dev/connect
 
-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.
+`<flung-connect>`: a panel that lets the people using your app connect and disconnect their social accounts through Flung, on your own page. A web component, a React component, and the calls underneath for a page that draws its own. No runtime dependencies.
+
+```bash
+npm install @flung.dev/connect
+```
+
+## How it works
+
+| Step | Where | What |
+|---|---|---|
+| 1 | Your server | Makes a connect token with your API key: `POST /v1/connect-tokens` with the page's origin. Keep the key there. |
+| 2 | Your page | Hands the token to `<flung-connect>`. |
+| 3 | The panel | Lists the platforms this Flung can connect and the accounts already connected. |
+| 4 | The person | Presses **Connect**. The platform's consent page opens in a small window; when they approve, the window closes and the account appears. |
+
+A connect token can only list, connect, reconnect and disconnect accounts, only from the origins it was made for, and stops working when it expires (one hour by default, at most one day). It cannot post, read the inbox or touch API keys.
+
+## Quick start
+
+**Your server** (any language; this is the SDK):
+
+```ts
+import { Flung } from '@flung.dev/sdk'
+
+const flung = new Flung({ apiKey: process.env.FLUNG_API_KEY! })
+
+// Behind your own sign-in: only make tokens for people who may manage this workspace's accounts.
+app.post('/connect-token', async (_request, response) => {
+  const { token } = await flung.connectTokens.create({ origins: ['https://app.example.com'], expiresIn: 900 })
+  response.json({ token })
+})
+```
+
+**Any page**:
+
+```html
+<script type="module">
+  import '@flung.dev/connect/register'
+
+  const panel = document.querySelector('flung-connect')
+  // A function: the panel asks again when a token expires.
+  panel.token = async () => (await (await fetch('/connect-token', { method: 'POST' })).json()).token
+  panel.addEventListener('flung-connect', (event) => console.log('Connected', event.detail.accounts))
+</script>
+
+<flung-connect platforms="x,linkedin,bluesky,mastodon"></flung-connect>
+```
+
+**React**:
+
+```tsx
+import { FlungConnect } from '@flung.dev/connect/react'
+
+export function Accounts() {
+  return <FlungConnect token={fetchConnectToken} platforms={['x', 'linkedin']} onConnect={({ accounts }) => console.log(accounts)} />
+}
+```
+
+[`examples/vanilla`](../../examples/vanilla) runs the whole thing with a server of a few lines and nothing to install.
+
+## Attributes and properties
+
+| Attribute | Property | Meaning |
+|---|---|---|
+| `token` | `token` | A connect token. The property also takes a function that returns a fresh one, which the panel calls again when the API says the token has expired. |
+| `base-url` | | The API. Production (`https://api.flung.dev`) when left out; `https://api-preview.flung.dev` for preview. |
+| `platforms` | | Offer only these, comma-separated. A token made with `platforms` is narrowed to those as well. |
+| `mode` | | `popup` (the default) opens a small window. `redirect` sends the whole page to the platform and back, for pages that cannot open windows; Flung returns to the same address, and the panel reports the result and tidies the address. |
+| `theme` | | `light` or `dark`. Follows the page's scheme when left out. |
+| | `labels` | Every word the panel shows, to put it in another language. See `DEFAULT_LABELS`. |
+| | `refresh()` | Reads the accounts again. |
+
+## Events
+
+| Event | `detail` | When |
+|---|---|---|
+| `flung-load` | `{ accounts }` | The accounts were read: on first show and after each change. |
+| `flung-connect` | `{ session, accounts }` | A connect or reconnect finished. Facebook stores one account per page. `session` is null after a redirect. |
+| `flung-disconnect` | `{ account }` | An account was disconnected. Its past posts keep their results. |
+| `flung-error` | `{ code, message }` | A call or a connect failed: `access_denied`, `wrong_account`, `forbidden`, `network_error` and so on. |
+
+Events bubble and cross the shadow root.
+
+## Looks
+
+The panel draws in a shadow root. Set any of `--flung-font`, `--flung-text`, `--flung-muted`, `--flung-surface`, `--flung-raised`, `--flung-border`, `--flung-accent`, `--flung-accent-text`, `--flung-danger`, `--flung-warning` and `--flung-radius` on the element, or style its parts with `::part()`: `panel`, `list`, `platform`, `badge`, `name`, `account`, `status`, `form`, `note`, `confirm`, `message`.
+
+```css
+flung-connect { --flung-accent: #0f766e; --flung-radius: 12px; }
+flung-connect::part(panel) { border: 0; }
+```
+
+## Behaviour worth knowing
+
+- **Popups.** Browsers open a window only straight from a click, so the panel opens it first and fills it in once Flung answers. When a browser blocks it anyway, the panel shows a link to the consent page instead.
+- **Waiting.** The panel waits on the connect session, not the window: some platforms' sign-in pages cut the link back to the page that opened them. Sessions last ten minutes. **Cancel** stops waiting.
+- **Mastodon and Bluesky** ask first: the person's Mastodon server (required), or their Bluesky handle (optional; without it they sign in through bsky.social).
+- **Reconnect** appears beside an account that needs it, or whose platform only lets Flung renew it for a limited time and that time ends within two weeks.
+- **Disconnect** asks to confirm. The account then drops from the panel; it stays in the API as `disconnected`.
+- **Safety.** Every name and message is set as text; nothing the API returns becomes markup. The panel sends the token to the API address only, and no cookie.
+
+## Without the element
+
+`@flung.dev/connect/core` has the calls (`ConnectClient`) and the flows (`connectInPopup`, `readRedirectResult`) for a page that draws its own panel.
+
+```ts
+import { ConnectClient, connectInPopup } from '@flung.dev/connect/core'
+
+const client = new ConnectClient({ token })
+button.onclick = async () => {
+  const outcome = await connectInPopup(client, () => client.connect('linkedin'))
+  if (outcome.kind === 'finished' && outcome.session.status === 'connected') render(await client.accounts())
+}
+```
+
+## Contents
+
+| Path | Purpose |
+|---|---|
+| `src/core/` | `ConnectClient`, the popup and redirect flows, platform names, and the API shapes it reads. No DOM needed except `window.open` in the popup flow. |
+| `src/element/` | `<flung-connect>`: the element, its styles, words, events and node helpers. |
+| `src/react/` | `<FlungConnect>`, the element for React. |
+| `src/register.ts` | The side-effect entry that registers the element. |
+| `src/__tests__/` | The client, flows, element and React component against a fake of the seven calls (`fake-api.ts`), in jsdom. |

package/dist/core/client.d.ts

@@ -0,0 +1,46 @@
+import type { Account, ConnectSession, Platform, PlatformInfo } from './types.js';
+export declare const DEFAULT_BASE_URL = "https://api.flung.dev";
+/** A connect token (`flung_ct_...`), or a function that fetches a fresh one from your server. */
+export type TokenSource = string | (() => Promise<string>);
+export interface ConnectClientOptions {
+    token: TokenSource;
+    /** Where the API lives. Defaults to production; `https://api-preview.flung.dev` for preview. */
+    baseUrl?: string | undefined;
+    /** A `fetch` to use instead of the global one. */
+    fetch?: typeof fetch | undefined;
+}
+/** A refused call: the API's stable `code` (`forbidden`, `not_configured`, ...) and its message. */
+export declare class FlungConnectError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: unknown;
+    readonly name = "FlungConnectError";
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+/**
+ * The calls a connect token may make, over `fetch`. A token source that is a function is asked again when the API says
+ * the token has expired, once per call, so a long-open page keeps working.
+ */
+export declare class ConnectClient {
+    #private;
+    constructor(options: ConnectClientOptions);
+    platforms(): Promise<PlatformInfo[]>;
+    accounts(): Promise<Account[]>;
+    /** Starts connecting a new account. `handle` is the Bluesky handle, or the Mastodon instance (required there). */
+    connect(platform: Platform, options?: {
+        handle?: string | undefined;
+        redirectUrl?: string | undefined;
+    }): Promise<ConnectSession>;
+    /** Starts reconnecting an account that needs it; the person must sign in as the same platform user. */
+    reconnect(accountId: string, options?: {
+        redirectUrl?: string | undefined;
+    }): Promise<ConnectSession>;
+    /** Deletes the account's stored tokens. It stays listed as `disconnected`. */
+    disconnect(accountId: string): Promise<Account>;
+    session(id: string): Promise<ConnectSession>;
+    /** Resolves once the session is no longer `pending`. Rejects with an `AbortError` when `signal` aborts. */
+    waitForSession(id: string, options?: {
+        signal?: AbortSignal | undefined;
+        intervalMs?: number | undefined;
+    }): Promise<ConnectSession>;
+}

package/dist/core/client.js

@@ -0,0 +1,109 @@
+export const DEFAULT_BASE_URL = 'https://api.flung.dev';
+const POLL_MS = 2_000;
+/** A refused call: the API's stable `code` (`forbidden`, `not_configured`, ...) and its message. */
+export class FlungConnectError extends Error {
+    status;
+    code;
+    details;
+    name = 'FlungConnectError';
+    constructor(status, code, message, details = undefined) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * The calls a connect token may make, over `fetch`. A token source that is a function is asked again when the API says
+ * the token has expired, once per call, so a long-open page keeps working.
+ */
+export class ConnectClient {
+    #baseUrl;
+    #fetch;
+    #source;
+    #token;
+    constructor(options) {
+        this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.#fetch = options.fetch ?? ((input, init) => fetch(input, init));
+        this.#source = options.token;
+        this.#token = typeof options.token === 'string' ? options.token : null;
+    }
+    async platforms() {
+        return (await this.#call('GET', '/v1/platforms')).data;
+    }
+    async accounts() {
+        return (await this.#call('GET', '/v1/accounts')).data;
+    }
+    /** Starts connecting a new account. `handle` is the Bluesky handle, or the Mastodon instance (required there). */
+    async connect(platform, options = {}) {
+        return this.#call('POST', `/v1/connect/${encodeURIComponent(platform)}`, compact({ handle: options.handle, redirectUrl: options.redirectUrl }));
+    }
+    /** Starts reconnecting an account that needs it; the person must sign in as the same platform user. */
+    async reconnect(accountId, options = {}) {
+        return this.#call('POST', `/v1/accounts/${encodeURIComponent(accountId)}/reconnect`, compact({ redirectUrl: options.redirectUrl }));
+    }
+    /** Deletes the account's stored tokens. It stays listed as `disconnected`. */
+    async disconnect(accountId) {
+        return this.#call('DELETE', `/v1/accounts/${encodeURIComponent(accountId)}`);
+    }
+    async session(id) {
+        return this.#call('GET', `/v1/connect-sessions/${encodeURIComponent(id)}`);
+    }
+    /** Resolves once the session is no longer `pending`. Rejects with an `AbortError` when `signal` aborts. */
+    async waitForSession(id, options = {}) {
+        for (;;) {
+            options.signal?.throwIfAborted();
+            const session = await this.session(id);
+            if (session.status !== 'pending')
+                return session;
+            await delay(options.intervalMs ?? POLL_MS, options.signal);
+        }
+    }
+    async #call(method, path, body) {
+        let response = await this.#send(method, path, body, await this.#currentToken(false));
+        if (response.status === 401 && typeof this.#source === 'function')
+            response = await this.#send(method, path, body, await this.#currentToken(true));
+        const text = await response.text();
+        const parsed = parse(text);
+        if (!response.ok) {
+            const error = parsed?.error;
+            throw new FlungConnectError(response.status, typeof error?.code === 'string' ? error.code : 'http_error', typeof error?.message === 'string' ? error.message : `Flung answered ${response.status}.`, error?.details);
+        }
+        return parsed;
+    }
+    #send(method, path, body, token) {
+        const headers = { authorization: `Bearer ${token}` };
+        if (body !== undefined)
+            headers['content-type'] = 'application/json';
+        return this.#fetch(`${this.#baseUrl}${path}`, { method, headers, ...(body === undefined ? {} : { body: JSON.stringify(body) }) }).catch((error) => {
+            throw new FlungConnectError(0, 'network_error', `Could not reach Flung: ${String(error)}`);
+        });
+    }
+    async #currentToken(fresh) {
+        if (typeof this.#source === 'string')
+            return this.#source;
+        if (this.#token === null || fresh)
+            this.#token = await this.#source();
+        return this.#token;
+    }
+}
+function compact(values) {
+    return Object.fromEntries(Object.entries(values).filter((entry) => entry[1] !== undefined));
+}
+function parse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        }, { once: true });
+    });
+}

package/dist/core/flows.d.ts

@@ -0,0 +1,36 @@
+import type { ConnectClient } from './client.js';
+import type { ConnectSession } from './types.js';
+/** How a connect in a window ended: the session, or `blocked` when the browser refused to open the window. */
+export type PopupOutcome = {
+    kind: 'finished';
+    session: ConnectSession;
+} | {
+    kind: 'blocked';
+    session: ConnectSession;
+};
+/**
+ * Opens the platform's consent page in a small window and resolves when the person finishes. Call it straight from a
+ * click: browsers open a window only during one, so it is opened before the session is asked for, then sent there.
+ *
+ * It waits on the session, not the window. A platform's sign-in page may cut the link back to this page, after which
+ * the window looks closed while the person is still in it, so only the session can say they are done. Abort `signal`
+ * to stop waiting (a Cancel button).
+ */
+export declare function connectInPopup(client: ConnectClient, start: () => Promise<ConnectSession>, options?: {
+    signal?: AbortSignal | undefined;
+    onStarted?: ((session: ConnectSession) => void) | undefined;
+}): Promise<PopupOutcome>;
+/** What Flung put on `redirectUrl` when a connect that left the page came back to it. */
+export interface RedirectResult {
+    sessionId: string;
+    status: 'connected' | 'error';
+    accountIds: string[];
+    error: {
+        code: string;
+        message: string;
+    } | null;
+}
+/** Reads the result from an address Flung sent the person back to, or null when it carries none. */
+export declare function readRedirectResult(address: string): RedirectResult | null;
+/** The address without Flung's result, to put back in the address bar once it is read. */
+export declare function withoutRedirectResult(address: string): string;

package/dist/core/flows.js

@@ -0,0 +1,59 @@
+const POPUP_NAME = 'flung-connect';
+const POPUP_FEATURES = 'popup,width=520,height=720';
+/**
+ * Opens the platform's consent page in a small window and resolves when the person finishes. Call it straight from a
+ * click: browsers open a window only during one, so it is opened before the session is asked for, then sent there.
+ *
+ * It waits on the session, not the window. A platform's sign-in page may cut the link back to this page, after which
+ * the window looks closed while the person is still in it, so only the session can say they are done. Abort `signal`
+ * to stop waiting (a Cancel button).
+ */
+export async function connectInPopup(client, start, options = {}) {
+    const popup = typeof window === 'undefined' ? null : window.open('', POPUP_NAME, POPUP_FEATURES);
+    let session;
+    try {
+        session = await start();
+    }
+    catch (error) {
+        popup?.close();
+        throw error;
+    }
+    options.onStarted?.(session);
+    if (session.authorizationUrl === null) {
+        popup?.close();
+        return { kind: 'finished', session };
+    }
+    if (popup === null)
+        return { kind: 'blocked', session };
+    popup.location.href = session.authorizationUrl;
+    try {
+        const finished = await client.waitForSession(session.id, { signal: options.signal });
+        return { kind: 'finished', session: finished };
+    }
+    finally {
+        // May do nothing once the platform cut the link; Flung's last page then says the window can be closed.
+        popup.close();
+    }
+}
+const PARAMS = ['flung_session_id', 'flung_status', 'flung_account_ids', 'flung_error', 'flung_message'];
+/** Reads the result from an address Flung sent the person back to, or null when it carries none. */
+export function readRedirectResult(address) {
+    const query = new URL(address).searchParams;
+    const sessionId = query.get('flung_session_id');
+    const status = query.get('flung_status');
+    if (sessionId === null || (status !== 'connected' && status !== 'error'))
+        return null;
+    return {
+        sessionId,
+        status,
+        accountIds: (query.get('flung_account_ids') ?? '').split(',').filter((id) => id !== ''),
+        error: status === 'error' ? { code: query.get('flung_error') ?? 'platform_error', message: query.get('flung_message') ?? '' } : null,
+    };
+}
+/** The address without Flung's result, to put back in the address bar once it is read. */
+export function withoutRedirectResult(address) {
+    const url = new URL(address);
+    for (const name of PARAMS)
+        url.searchParams.delete(name);
+    return url.toString();
+}

package/dist/core/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@flung.dev/connect/core`: the connect calls and flows with no element, for a page that draws its own panel.
+ */
+export { ConnectClient, DEFAULT_BASE_URL, FlungConnectError } from './client.js';
+export type { ConnectClientOptions, TokenSource } from './client.js';
+export { connectInPopup, readRedirectResult, withoutRedirectResult } from './flows.js';
+export type { PopupOutcome, RedirectResult } from './flows.js';
+export { HANDLE_PROMPT, isPlatform, parsePlatformList, PLATFORM_NAMES, tokenPlatforms } from './platforms.js';
+export { PLATFORMS } from './types.js';
+export type { Account, AccountStatus, ConnectSession, ConnectSessionStatus, Platform, PlatformInfo } from './types.js';

package/dist/core/index.js

@@ -0,0 +1,7 @@
+/**
+ * `@flung.dev/connect/core`: the connect calls and flows with no element, for a page that draws its own panel.
+ */
+export { ConnectClient, DEFAULT_BASE_URL, FlungConnectError } from './client.js';
+export { connectInPopup, readRedirectResult, withoutRedirectResult } from './flows.js';
+export { HANDLE_PROMPT, isPlatform, parsePlatformList, PLATFORM_NAMES, tokenPlatforms } from './platforms.js';
+export { PLATFORMS } from './types.js';

package/dist/core/platforms.d.ts

@@ -0,0 +1,14 @@
+import type { Platform } from './types.js';
+export declare const PLATFORM_NAMES: Readonly<Record<Platform, string>>;
+/** What a connect asks the person for first: Mastodon needs their instance; Bluesky takes a handle when they have one. */
+export declare const HANDLE_PROMPT: Readonly<Partial<Record<Platform, {
+    required: boolean;
+}>>>;
+export declare function isPlatform(value: string): value is Platform;
+/** `x, linkedin` as platforms, dropping anything that is not one. Null for an empty or missing list. */
+export declare function parsePlatformList(value: string | null | undefined): Platform[] | null;
+/**
+ * The platforms a connect token was made for, read from its payload so the panel offers only those. Only a hint: the
+ * API checks the signature and refuses the rest. Null when the token names none or cannot be read.
+ */
+export declare function tokenPlatforms(token: string): Platform[] | null;

package/dist/core/platforms.js

@@ -0,0 +1,49 @@
+import { PLATFORMS } from './types.js';
+export const PLATFORM_NAMES = {
+    x: 'X',
+    instagram: 'Instagram',
+    facebook: 'Facebook',
+    threads: 'Threads',
+    linkedin: 'LinkedIn',
+    tiktok: 'TikTok',
+    youtube: 'YouTube',
+    pinterest: 'Pinterest',
+    bluesky: 'Bluesky',
+    mastodon: 'Mastodon',
+    discord: 'Discord',
+    farcaster: 'Farcaster',
+};
+/** What a connect asks the person for first: Mastodon needs their instance; Bluesky takes a handle when they have one. */
+export const HANDLE_PROMPT = {
+    mastodon: { required: true },
+    bluesky: { required: false },
+};
+export function isPlatform(value) {
+    return PLATFORMS.includes(value);
+}
+/** `x, linkedin` as platforms, dropping anything that is not one. Null for an empty or missing list. */
+export function parsePlatformList(value) {
+    if (value === null || value === undefined)
+        return null;
+    const platforms = value
+        .split(',')
+        .map((part) => part.trim().toLowerCase())
+        .filter(isPlatform);
+    return platforms.length === 0 ? null : [...new Set(platforms)];
+}
+/**
+ * The platforms a connect token was made for, read from its payload so the panel offers only those. Only a hint: the
+ * API checks the signature and refuses the rest. Null when the token names none or cannot be read.
+ */
+export function tokenPlatforms(token) {
+    const body = /^flung_ct_([\w-]+)\./.exec(token)?.[1];
+    if (body === undefined)
+        return null;
+    try {
+        const payload = JSON.parse(atob(body.replace(/-/g, '+').replace(/_/g, '/')));
+        return Array.isArray(payload.pl) ? payload.pl.filter((value) => typeof value === 'string' && isPlatform(value)) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The few shapes of the Flung API a connect panel reads, written out here so the package needs nothing else. They are
+ * the API's own (`spec/openapi.json`): `PlatformInfo`, `Account` and `ConnectSession`, trimmed to what is used.
+ */
+export declare const PLATFORMS: readonly ['x', 'instagram', 'facebook', 'threads', 'linkedin', 'tiktok', 'youtube', 'pinterest', 'bluesky', 'mastodon', 'discord', 'farcaster'];
+export type Platform = (typeof PLATFORMS)[number];
+export interface PlatformInfo {
+    platform: Platform;
+    /** Whether this Flung has the platform's app credentials, so accounts can be connected. */
+    connectable: boolean;
+}
+export type AccountStatus = 'active' | 'needs_reconnect' | 'disconnected';
+export interface Account {
+    id: string;
+    platform: Platform;
+    platformUserId: string;
+    username: string | null;
+    profileId: string | null;
+    status: AccountStatus;
+    /** When the person must reconnect by, for platforms whose connections cannot be renewed forever. */
+    reconnectBy: string | null;
+    createdAt: string;
+}
+export type ConnectSessionStatus = 'pending' | 'connected' | 'failed' | 'expired';
+export interface ConnectSession {
+    id: string;
+    platform: Platform;
+    /** The account being reconnected; null for a new connection. */
+    accountId: string | null;
+    status: ConnectSessionStatus;
+    /** The platform's consent page, while the session is pending. */
+    authorizationUrl: string | null;
+    expiresAt: string;
+    /** The accounts stored, once connected. Facebook connects one per page. */
+    accountIds: string[];
+    error: {
+        code: string;
+        message: string;
+    } | null;
+}

package/dist/core/types.js

@@ -0,0 +1,5 @@
+/**
+ * The few shapes of the Flung API a connect panel reads, written out here so the package needs nothing else. They are
+ * the API's own (`spec/openapi.json`): `PlatformInfo`, `Account` and `ConnectSession`, trimmed to what is used.
+ */
+export const PLATFORMS = ['x', 'instagram', 'facebook', 'threads', 'linkedin', 'tiktok', 'youtube', 'pinterest', 'bluesky', 'mastodon', 'discord', 'farcaster'];

package/dist/element/copy.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Every word the panel shows, in English. Pass `labels` to put it in another language; `{platform}`, `{account}`,
+ * `{message}` and `{date}` are filled in where a label has them.
+ */
+export interface ConnectLabels {
+    /** The panel's name for a screen reader. */
+    panel: string;
+    connect: string;
+    connectAnother: string;
+    reconnect: string;
+    disconnect: string;
+    confirmDisconnect: string;
+    keep: string;
+    cancel: string;
+    continue: string;
+    handleBluesky: string;
+    handleMastodon: string;
+    waiting: string;
+    blocked: string;
+    openSignIn: string;
+    connected: string;
+    failed: string;
+    expired: string;
+    disconnected: string;
+    needsReconnect: string;
+    reconnectBy: string;
+    loading: string;
+    loadFailed: string;
+    empty: string;
+    noToken: string;
+}
+export declare const DEFAULT_LABELS: ConnectLabels;
+export declare function format(template: string, values: Readonly<Record<string, string>>): string;

package/dist/element/copy.js

@@ -0,0 +1,29 @@
+export const DEFAULT_LABELS = {
+    panel: 'Connected accounts',
+    connect: 'Connect',
+    connectAnother: 'Add another',
+    reconnect: 'Reconnect',
+    disconnect: 'Disconnect',
+    confirmDisconnect: 'Disconnect {account}? Posts to it will stop.',
+    keep: 'Keep it',
+    cancel: 'Cancel',
+    continue: 'Continue',
+    handleBluesky: 'Your Bluesky handle, such as alice.bsky.social (optional)',
+    handleMastodon: 'Your Mastodon server, such as mastodon.social',
+    waiting: 'Finish signing in to {platform} in the window that opened.',
+    blocked: 'Your browser did not open the {platform} window.',
+    openSignIn: 'Open {platform} sign-in',
+    connected: '{platform} is connected.',
+    failed: '{platform} was not connected: {message}',
+    expired: 'Signing in to {platform} took too long. Try again.',
+    disconnected: '{account} is disconnected.',
+    needsReconnect: 'Needs reconnecting',
+    reconnectBy: 'Reconnect by {date}',
+    loading: 'Loading accounts…',
+    loadFailed: 'Could not load accounts: {message}',
+    empty: 'There is nothing to connect here.',
+    noToken: 'This panel has no connect token yet.',
+};
+export function format(template, values) {
+    return template.replace(/\{(\w+)\}/g, (whole, name) => values[name] ?? whole);
+}

package/dist/element/define.d.ts

@@ -0,0 +1,7 @@
+/** The element's tag. */
+export declare const TAG_NAME = "flung-connect";
+/**
+ * Registers `<flung-connect>` once. Safe to call many times, from several copies of the package on one page, and where
+ * there is no `customElements` (a server render), where it does nothing.
+ */
+export declare function defineFlungConnect(tag?: string): void;

package/dist/element/define.js

@@ -0,0 +1,12 @@
+import { createFlungConnectClass } from './flung-connect.js';
+/** The element's tag. */
+export const TAG_NAME = 'flung-connect';
+/**
+ * Registers `<flung-connect>` once. Safe to call many times, from several copies of the package on one page, and where
+ * there is no `customElements` (a server render), where it does nothing.
+ */
+export function defineFlungConnect(tag = TAG_NAME) {
+    if (typeof customElements === 'undefined' || customElements.get(tag) !== undefined)
+        return;
+    customElements.define(tag, createFlungConnectClass());
+}

package/dist/element/dom.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Building the element's own nodes with `createElement`, never from a string of HTML, so nothing the API or a page
+ * supplies (an account name, an error message) can become markup. Attributes go through `setAttribute`, text through
+ * `textContent`.
+ */
+import type { Account } from '../core/types.js';
+type Attributes = Readonly<Record<string, string | number | boolean | undefined>>;
+/** An HTML element of the element's own. `true` sets an empty attribute; `false` and `undefined` set none. */
+export declare function html<K extends keyof HTMLElementTagNameMap>(tag: K, attributes?: Attributes, ...children: (Node | string | null)[]): HTMLElementTagNameMap[K];
+/** How an account is named in the panel: its username, or its platform id when it has none. */
+export declare function displayName(account: Account): string;
+/** A button that calls `onClick`, with a `data-key` so focus can be put back on it after the panel is drawn again. */
+export declare function button(text: string, key: string, onClick: () => void, options?: {
+    primary?: boolean;
+    danger?: boolean;
+    disabled?: boolean;
+    label?: string;
+}): HTMLButtonElement;
+export {};

package/dist/element/dom.js

@@ -0,0 +1,29 @@
+/**
+ * Building the element's own nodes with `createElement`, never from a string of HTML, so nothing the API or a page
+ * supplies (an account name, an error message) can become markup. Attributes go through `setAttribute`, text through
+ * `textContent`.
+ */
+/** An HTML element of the element's own. `true` sets an empty attribute; `false` and `undefined` set none. */
+export function html(tag, attributes = {}, ...children) {
+    const element = document.createElement(tag);
+    for (const [name, value] of Object.entries(attributes)) {
+        if (value === undefined || value === false)
+            continue;
+        element.setAttribute(name, value === true ? '' : String(value));
+    }
+    for (const child of children)
+        if (child !== null)
+            element.append(child);
+    return element;
+}
+/** How an account is named in the panel: its username, or its platform id when it has none. */
+export function displayName(account) {
+    return account.username ?? account.platformUserId;
+}
+/** A button that calls `onClick`, with a `data-key` so focus can be put back on it after the panel is drawn again. */
+export function button(text, key, onClick, options = {}) {
+    const className = options.primary === true ? 'primary' : options.danger === true ? 'danger' : undefined;
+    const element = html('button', { type: 'button', class: className, 'data-key': key, disabled: options.disabled === true, 'aria-label': options.label }, text);
+    element.addEventListener('click', onClick);
+    return element;
+}

package/dist/element/events.d.ts

@@ -0,0 +1,25 @@
+import type { Account, ConnectSession } from '../core/types.js';
+/** `flung-load`: the accounts were read, on first show and after every change. */
+export interface LoadDetail {
+    accounts: Account[];
+}
+/** `flung-connect`: a connect or reconnect finished. `accounts` are the ones stored; Facebook stores one per page. */
+export interface ConnectDetail {
+    session: ConnectSession | null;
+    accounts: Account[];
+}
+/** `flung-disconnect`: an account was disconnected. */
+export interface DisconnectDetail {
+    account: Account;
+}
+/** `flung-error`: a call or a connect failed. `code` is the API's stable code, such as `forbidden` or `access_denied`. */
+export interface ErrorDetail {
+    code: string;
+    message: string;
+}
+export interface FlungConnectEventMap {
+    'flung-load': CustomEvent<LoadDetail>;
+    'flung-connect': CustomEvent<ConnectDetail>;
+    'flung-disconnect': CustomEvent<DisconnectDetail>;
+    'flung-error': CustomEvent<ErrorDetail>;
+}

package/dist/element/events.js

@@ -0,0 +1 @@
+export {};

package/dist/element/flung-connect.d.ts

@@ -0,0 +1,13 @@
+import type { TokenSource } from '../core/client.js';
+import type { ConnectLabels } from './copy.js';
+/** `<flung-connect>` as a page sees it. */
+export interface FlungConnectElement extends HTMLElement {
+    /** A connect token, or a function that fetches a fresh one from your server. The `token` attribute sets a string. */
+    token: TokenSource | null;
+    get labels(): ConnectLabels;
+    set labels(value: Partial<ConnectLabels> | undefined);
+    /** Reads the accounts again, as after a connect. */
+    refresh(): Promise<void>;
+}
+/** Builds the class on first use, so importing the package on a server, where there is no `HTMLElement`, is safe. */
+export declare function createFlungConnectClass(): new () => FlungConnectElement;

package/dist/element/flung-connect.js

@@ -0,0 +1,251 @@
+import { ConnectClient, FlungConnectError } from '../core/client.js';
+import { connectInPopup, readRedirectResult, withoutRedirectResult } from '../core/flows.js';
+import { HANDLE_PROMPT, parsePlatformList, PLATFORM_NAMES, tokenPlatforms } from '../core/platforms.js';
+import { DEFAULT_LABELS, format } from './copy.js';
+import { button, displayName, html } from './dom.js';
+import { STYLES } from './styles.js';
+/** How soon a reconnect deadline is worth showing. */
+const SOON_MS = 14 * 86_400_000;
+/** Builds the class on first use, so importing the package on a server, where there is no `HTMLElement`, is safe. */
+export function createFlungConnectClass() {
+    return class FlungConnect extends HTMLElement {
+        static observedAttributes = ['token', 'base-url', 'platforms'];
+        #root = this.attachShadow({ mode: 'open' });
+        #source = null;
+        #client = null;
+        #labels = DEFAULT_LABELS;
+        #platforms = [];
+        #accounts = [];
+        #rows = new Map();
+        #message = { text: '', error: false };
+        #focus = null;
+        #started = false;
+        get token() {
+            return this.#source;
+        }
+        set token(value) {
+            this.#source = value;
+            this.#reset();
+        }
+        get labels() {
+            return this.#labels;
+        }
+        set labels(value) {
+            this.#labels = { ...DEFAULT_LABELS, ...value };
+            this.#render();
+        }
+        refresh() {
+            return this.#load();
+        }
+        connectedCallback() {
+            if (this.#started)
+                return;
+            this.#started = true;
+            if (this.#source === null && this.hasAttribute('token'))
+                this.#source = this.getAttribute('token');
+            this.#reset();
+        }
+        attributeChangedCallback(name, previous, next) {
+            if (previous === next || !this.#started)
+                return;
+            if (name === 'token')
+                this.#source = next;
+            if (name === 'platforms')
+                void this.#load();
+            else
+                this.#reset();
+        }
+        #reset() {
+            if (!this.#started)
+                return;
+            for (const row of this.#rows.values())
+                if (row.kind === 'waiting')
+                    row.abort.abort();
+            this.#rows.clear();
+            this.#client = this.#source === null ? null : new ConnectClient({ token: this.#source, baseUrl: this.getAttribute('base-url') ?? undefined });
+            void this.#load().then(() => this.#readReturn());
+        }
+        async #load() {
+            const client = this.#client;
+            if (client === null)
+                return this.#say(this.#labels.noToken);
+            if (this.#platforms.length === 0)
+                this.#say(this.#labels.loading);
+            try {
+                const [platforms, accounts] = await Promise.all([client.platforms(), client.accounts()]);
+                const asked = parsePlatformList(this.getAttribute('platforms'));
+                const granted = typeof this.#source === 'string' ? tokenPlatforms(this.#source) : null;
+                this.#platforms = platforms.map((info) => info.platform).filter((platform) => platforms.find((info) => info.platform === platform)?.connectable === true && (asked ?? [platform]).includes(platform) && (granted ?? [platform]).includes(platform));
+                this.#accounts = accounts.filter((account) => account.status !== 'disconnected' && this.#platforms.includes(account.platform));
+                if (this.#message.text === this.#labels.loading || this.#message.text === this.#labels.noToken)
+                    this.#message = { text: this.#platforms.length === 0 ? this.#labels.empty : '', error: false };
+                this.#render();
+                this.#emit('flung-load', { accounts: this.#accounts });
+            }
+            catch (error) {
+                this.#fail(error, (message) => format(this.#labels.loadFailed, { message }));
+            }
+        }
+        /** A connect that left the page (`mode="redirect"`) and came back: report it, and take Flung's result off the address. */
+        #readReturn() {
+            if (typeof location === 'undefined')
+                return;
+            const result = readRedirectResult(location.href);
+            if (result === null)
+                return;
+            history.replaceState(history.state, '', withoutRedirectResult(location.href));
+            if (result.status === 'connected') {
+                const accounts = this.#accounts.filter((account) => result.accountIds.includes(account.id));
+                const platform = accounts[0]?.platform;
+                this.#say(format(this.#labels.connected, { platform: platform === undefined ? 'The account' : PLATFORM_NAMES[platform] }));
+                this.#emit('flung-connect', { session: null, accounts });
+            }
+            else {
+                this.#say(result.error?.message ?? '', true);
+                this.#emit('flung-error', { code: result.error?.code ?? 'platform_error', message: result.error?.message ?? '' });
+            }
+        }
+        /** Called straight from a click or a submit: a window can only be opened during one. */
+        #start(platform, account, handle) {
+            const client = this.#client;
+            if (client === null)
+                return;
+            const redirect = this.getAttribute('mode') === 'redirect';
+            const redirectUrl = redirect ? withoutRedirectResult(location.href) : undefined;
+            const begin = () => (account === null ? client.connect(platform, { handle, redirectUrl }) : client.reconnect(account.id, { redirectUrl }));
+            const abort = new AbortController();
+            const row = { kind: 'waiting', abort, blockedUrl: null };
+            this.#rows.set(platform, row);
+            this.#say('');
+            if (redirect) {
+                void begin().then((session) => session.authorizationUrl !== null && location.assign(session.authorizationUrl), (error) => this.#settle(platform, error));
+                return;
+            }
+            void connectInPopup(client, begin, { signal: abort.signal })
+                .then(async (outcome) => {
+                if (outcome.kind === 'finished')
+                    return outcome.session;
+                row.blockedUrl = outcome.session.authorizationUrl;
+                this.#render();
+                return client.waitForSession(outcome.session.id, { signal: abort.signal });
+            })
+                .then((session) => this.#finish(platform, session), (error) => this.#settle(platform, error));
+        }
+        async #finish(platform, session) {
+            this.#rows.set(platform, { kind: 'idle' });
+            const name = PLATFORM_NAMES[platform];
+            if (session.status === 'connected') {
+                await this.#load();
+                this.#say(format(this.#labels.connected, { platform: name }));
+                this.#emit('flung-connect', { session, accounts: this.#accounts.filter((account) => session.accountIds.includes(account.id)) });
+            }
+            else if (session.status === 'expired') {
+                this.#say(format(this.#labels.expired, { platform: name }), true);
+                this.#emit('flung-error', { code: 'expired', message: this.#message.text });
+            }
+            else {
+                const message = session.error?.message ?? '';
+                this.#say(format(this.#labels.failed, { platform: name, message }), true);
+                this.#emit('flung-error', { code: session.error?.code ?? 'platform_error', message });
+            }
+        }
+        /** A connect that stopped early: cancelled by the person, or refused by the API. */
+        #settle(platform, error) {
+            this.#rows.set(platform, { kind: 'idle' });
+            if (error instanceof DOMException && error.name === 'AbortError')
+                return this.#render();
+            this.#fail(error, (message) => format(this.#labels.failed, { platform: PLATFORM_NAMES[platform], message }));
+        }
+        async #disconnect(account) {
+            this.#rows.set(account.platform, { kind: 'idle' });
+            try {
+                const disconnected = await this.#client.disconnect(account.id);
+                await this.#load();
+                this.#say(format(this.#labels.disconnected, { account: displayName(account) }));
+                this.#emit('flung-disconnect', { account: disconnected });
+            }
+            catch (error) {
+                this.#fail(error, (message) => message);
+            }
+        }
+        #fail(error, say) {
+            const detail = error instanceof FlungConnectError ? { code: error.code, message: error.message } : { code: 'unknown', message: String(error) };
+            this.#say(say(detail.message), true);
+            this.#emit('flung-error', detail);
+        }
+        #say(text, error = false) {
+            this.#message = { text, error };
+            this.#render();
+        }
+        #emit(type, detail) {
+            this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
+        }
+        #render() {
+            const active = this.#root.activeElement instanceof HTMLElement ? (this.#root.activeElement.dataset['key'] ?? null) : null;
+            const list = html('ul', { class: 'list', part: 'list' }, ...this.#platforms.map((platform) => this.#platformRow(platform)));
+            const message = html('p', { class: this.#message.error ? 'message error' : 'message', part: 'message', role: 'status', 'aria-live': 'polite' }, this.#message.text);
+            const panel = html('section', { class: 'panel', part: 'panel', 'aria-label': this.#labels.panel }, list, message);
+            this.#root.replaceChildren(html('style', {}, STYLES), panel);
+            const key = this.#focus ?? active;
+            this.#focus = null;
+            if (key !== null)
+                this.#root.querySelector(`[data-key="${key}"]`)?.focus();
+        }
+        #platformRow(platform) {
+            const name = PLATFORM_NAMES[platform];
+            const state = this.#rows.get(platform) ?? { kind: 'idle' };
+            const busy = state.kind === 'waiting';
+            const accounts = this.#accounts.filter((account) => account.platform === platform);
+            const connect = button(accounts.length === 0 ? this.#labels.connect : this.#labels.connectAnother, `connect-${platform}`, () => this.#askOrStart(platform), { primary: accounts.length === 0, disabled: busy, label: `${accounts.length === 0 ? this.#labels.connect : this.#labels.connectAnother} ${name}` });
+            const row = html('div', { class: 'row' }, html('span', { class: 'badge', part: 'badge', 'aria-hidden': 'true' }, name.slice(0, 2)), html('span', { class: 'name', part: 'name' }, name), connect);
+            const items = accounts.map((account) => this.#accountRow(account, busy));
+            return html('li', { class: 'platform', part: 'platform', 'data-platform': platform }, row, items.length === 0 ? null : html('ul', { class: 'accounts' }, ...items), this.#rowExtra(platform, state));
+        }
+        #accountRow(account, busy) {
+            const due = account.reconnectBy === null ? null : new Date(account.reconnectBy);
+            const status = account.status === 'needs_reconnect' ? this.#labels.needsReconnect : due !== null && due.getTime() - Date.now() < SOON_MS ? format(this.#labels.reconnectBy, { date: due.toLocaleDateString() }) : null;
+            return html('li', { class: 'account', part: 'account', 'data-account': account.id }, html('span', { class: 'who' }, displayName(account)), status === null ? null : html('span', { class: 'status', part: 'status' }, status), status === null ? null : button(this.#labels.reconnect, `reconnect-${account.id}`, () => this.#start(account.platform, account, undefined), { disabled: busy }), button(this.#labels.disconnect, `disconnect-${account.id}`, () => this.#confirm(account), { danger: true, disabled: busy, label: `${this.#labels.disconnect} ${displayName(account)}` }));
+        }
+        #rowExtra(platform, state) {
+            const name = PLATFORM_NAMES[platform];
+            if (state.kind === 'handle') {
+                const id = `handle-${platform}`;
+                const required = HANDLE_PROMPT[platform]?.required === true;
+                const input = html('input', { id, name: 'handle', 'data-key': id, autocomplete: 'username', spellcheck: 'false', required });
+                const form = html('form', { class: 'form', part: 'form' }, html('label', { for: id }, platform === 'mastodon' ? this.#labels.handleMastodon : this.#labels.handleBluesky), input, html('button', { type: 'submit', class: 'primary', 'data-key': `continue-${platform}` }, this.#labels.continue), button(this.#labels.cancel, `cancel-${platform}`, () => this.#idle(platform)));
+                form.addEventListener('submit', (event) => {
+                    event.preventDefault();
+                    const handle = input.value.trim();
+                    this.#start(platform, null, handle === '' ? undefined : handle);
+                });
+                return form;
+            }
+            if (state.kind === 'waiting') {
+                const link = state.blockedUrl === null ? null : html('a', { href: state.blockedUrl, target: '_blank', rel: 'noopener' }, format(this.#labels.openSignIn, { platform: name }));
+                const text = state.blockedUrl === null ? format(this.#labels.waiting, { platform: name }) : `${format(this.#labels.blocked, { platform: name })} `;
+                return html('p', { class: 'note', part: 'note' }, text, link, ' ', button(this.#labels.cancel, `cancel-${platform}`, () => (state.abort.abort(), this.#idle(platform))));
+            }
+            if (state.kind === 'confirm') {
+                return html('div', { class: 'confirm', part: 'confirm' }, html('p', {}, format(this.#labels.confirmDisconnect, { account: displayName(state.account) })), button(this.#labels.disconnect, `confirm-${platform}`, () => void this.#disconnect(state.account), { danger: true }), button(this.#labels.keep, `keep-${platform}`, () => this.#idle(platform)));
+            }
+            return null;
+        }
+        #askOrStart(platform) {
+            if (HANDLE_PROMPT[platform] === undefined)
+                return this.#start(platform, null, undefined);
+            this.#rows.set(platform, { kind: 'handle' });
+            this.#focus = `handle-${platform}`;
+            this.#render();
+        }
+        #confirm(account) {
+            this.#rows.set(account.platform, { kind: 'confirm', account });
+            this.#focus = `keep-${account.platform}`;
+            this.#render();
+        }
+        #idle(platform) {
+            this.#rows.set(platform, { kind: 'idle' });
+            this.#focus = `connect-${platform}`;
+            this.#render();
+        }
+    };
+}

package/dist/element/styles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The panel's look, inside its shadow root. Every colour, the font and the corner radius are `--flung-*` properties a
+ * page can set on the element; each part has a `part` name for `::part()`. Follows the page's light or dark scheme
+ * unless `theme` says which.
+ */
+export declare const STYLES = "\n:host {\n  --flung-font: system-ui, -apple-system, \"Segoe UI\", sans-serif;\n  --flung-text: #18181b;\n  --flung-muted: #52525b;\n  --flung-surface: #ffffff;\n  --flung-raised: #f4f4f5;\n  --flung-border: #d4d4d8;\n  --flung-accent: #18181b;\n  --flung-accent-text: #ffffff;\n  --flung-danger: #b91c1c;\n  --flung-warning: #a16207;\n  --flung-radius: 8px;\n  display: block;\n  font: 15px/1.45 var(--flung-font);\n  color: var(--flung-text);\n}\n:host([hidden]) { display: none; }\n@media (prefers-color-scheme: dark) {\n  :host(:not([theme=\"light\"])) {\n    --flung-text: #f4f4f5;\n    --flung-muted: #a1a1aa;\n    --flung-surface: #18181b;\n    --flung-raised: #27272a;\n    --flung-border: #3f3f46;\n    --flung-accent: #f4f4f5;\n    --flung-accent-text: #18181b;\n    --flung-danger: #f87171;\n    --flung-warning: #facc15;\n  }\n}\n:host([theme=\"dark\"]) {\n  --flung-text: #f4f4f5;\n  --flung-muted: #a1a1aa;\n  --flung-surface: #18181b;\n  --flung-raised: #27272a;\n  --flung-border: #3f3f46;\n  --flung-accent: #f4f4f5;\n  --flung-accent-text: #18181b;\n  --flung-danger: #f87171;\n  --flung-warning: #facc15;\n}\n* { box-sizing: border-box; }\n.panel { background: var(--flung-surface); border: 1px solid var(--flung-border); border-radius: var(--flung-radius); overflow: hidden; }\nul { list-style: none; margin: 0; padding: 0; }\n.platform { padding: 12px 14px; border-top: 1px solid var(--flung-border); }\n.platform:first-child { border-top: 0; }\n.row { display: flex; align-items: center; gap: 10px; min-height: 36px; }\n.badge { flex: none; width: 32px; height: 32px; border-radius: 50%; display: grid; place-items: center; background: var(--flung-raised); font-weight: 600; font-size: 13px; }\n.name { flex: 1; min-width: 0; font-weight: 600; }\n.accounts { margin: 6px 0 0 42px; }\n.account { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; padding: 4px 0; }\n.who { flex: 1; min-width: 8rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n.status { font-size: 13px; color: var(--flung-warning); }\n.note { margin: 8px 0 0 42px; color: var(--flung-muted); font-size: 14px; }\n.note a { color: inherit; }\n.confirm, .form { margin: 8px 0 0 42px; display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }\n.confirm p { flex-basis: 100%; margin: 0; }\n.form label { flex-basis: 100%; font-size: 14px; color: var(--flung-muted); }\n.form input { flex: 1; min-width: 10rem; font: inherit; color: inherit; background: var(--flung-surface); border: 1px solid var(--flung-border); border-radius: calc(var(--flung-radius) - 2px); padding: 6px 10px; }\nbutton { font: inherit; font-size: 14px; cursor: pointer; border-radius: calc(var(--flung-radius) - 2px); padding: 6px 12px; border: 1px solid var(--flung-border); background: transparent; color: inherit; }\nbutton.primary { background: var(--flung-accent); border-color: var(--flung-accent); color: var(--flung-accent-text); }\nbutton.danger { color: var(--flung-danger); border-color: currentColor; }\nbutton:disabled { opacity: .55; cursor: default; }\nbutton:focus-visible, input:focus-visible, a:focus-visible { outline: 2px solid var(--flung-accent); outline-offset: 2px; }\n.message { margin: 0; padding: 10px 14px; border-top: 1px solid var(--flung-border); color: var(--flung-muted); font-size: 14px; }\n.message:empty { display: none; }\n.message.error { color: var(--flung-danger); }\n@media (prefers-reduced-motion: no-preference) { button { transition: opacity .15s; } }\n";

package/dist/element/styles.js

@@ -0,0 +1,75 @@
+/**
+ * The panel's look, inside its shadow root. Every colour, the font and the corner radius are `--flung-*` properties a
+ * page can set on the element; each part has a `part` name for `::part()`. Follows the page's light or dark scheme
+ * unless `theme` says which.
+ */
+export const STYLES = `
+:host {
+  --flung-font: system-ui, -apple-system, "Segoe UI", sans-serif;
+  --flung-text: #18181b;
+  --flung-muted: #52525b;
+  --flung-surface: #ffffff;
+  --flung-raised: #f4f4f5;
+  --flung-border: #d4d4d8;
+  --flung-accent: #18181b;
+  --flung-accent-text: #ffffff;
+  --flung-danger: #b91c1c;
+  --flung-warning: #a16207;
+  --flung-radius: 8px;
+  display: block;
+  font: 15px/1.45 var(--flung-font);
+  color: var(--flung-text);
+}
+:host([hidden]) { display: none; }
+@media (prefers-color-scheme: dark) {
+  :host(:not([theme="light"])) {
+    --flung-text: #f4f4f5;
+    --flung-muted: #a1a1aa;
+    --flung-surface: #18181b;
+    --flung-raised: #27272a;
+    --flung-border: #3f3f46;
+    --flung-accent: #f4f4f5;
+    --flung-accent-text: #18181b;
+    --flung-danger: #f87171;
+    --flung-warning: #facc15;
+  }
+}
+:host([theme="dark"]) {
+  --flung-text: #f4f4f5;
+  --flung-muted: #a1a1aa;
+  --flung-surface: #18181b;
+  --flung-raised: #27272a;
+  --flung-border: #3f3f46;
+  --flung-accent: #f4f4f5;
+  --flung-accent-text: #18181b;
+  --flung-danger: #f87171;
+  --flung-warning: #facc15;
+}
+* { box-sizing: border-box; }
+.panel { background: var(--flung-surface); border: 1px solid var(--flung-border); border-radius: var(--flung-radius); overflow: hidden; }
+ul { list-style: none; margin: 0; padding: 0; }
+.platform { padding: 12px 14px; border-top: 1px solid var(--flung-border); }
+.platform:first-child { border-top: 0; }
+.row { display: flex; align-items: center; gap: 10px; min-height: 36px; }
+.badge { flex: none; width: 32px; height: 32px; border-radius: 50%; display: grid; place-items: center; background: var(--flung-raised); font-weight: 600; font-size: 13px; }
+.name { flex: 1; min-width: 0; font-weight: 600; }
+.accounts { margin: 6px 0 0 42px; }
+.account { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; padding: 4px 0; }
+.who { flex: 1; min-width: 8rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.status { font-size: 13px; color: var(--flung-warning); }
+.note { margin: 8px 0 0 42px; color: var(--flung-muted); font-size: 14px; }
+.note a { color: inherit; }
+.confirm, .form { margin: 8px 0 0 42px; display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
+.confirm p { flex-basis: 100%; margin: 0; }
+.form label { flex-basis: 100%; font-size: 14px; color: var(--flung-muted); }
+.form input { flex: 1; min-width: 10rem; font: inherit; color: inherit; background: var(--flung-surface); border: 1px solid var(--flung-border); border-radius: calc(var(--flung-radius) - 2px); padding: 6px 10px; }
+button { font: inherit; font-size: 14px; cursor: pointer; border-radius: calc(var(--flung-radius) - 2px); padding: 6px 12px; border: 1px solid var(--flung-border); background: transparent; color: inherit; }
+button.primary { background: var(--flung-accent); border-color: var(--flung-accent); color: var(--flung-accent-text); }
+button.danger { color: var(--flung-danger); border-color: currentColor; }
+button:disabled { opacity: .55; cursor: default; }
+button:focus-visible, input:focus-visible, a:focus-visible { outline: 2px solid var(--flung-accent); outline-offset: 2px; }
+.message { margin: 0; padding: 10px 14px; border-top: 1px solid var(--flung-border); color: var(--flung-muted); font-size: 14px; }
+.message:empty { display: none; }
+.message.error { color: var(--flung-danger); }
+@media (prefers-reduced-motion: no-preference) { button { transition: opacity .15s; } }
+`;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@flung.dev/connect`: `<flung-connect>`, a panel that lets people connect and disconnect their social accounts
+ * from your page, with a connect token your server makes. `import '@flung.dev/connect/register'` to register it,
+ * or call `defineFlungConnect()`.
+ */
+export { defineFlungConnect, TAG_NAME } from './element/define.js';
+export type { FlungConnectElement } from './element/flung-connect.js';
+export { DEFAULT_LABELS } from './element/copy.js';
+export type { ConnectLabels } from './element/copy.js';
+export type { ConnectDetail, DisconnectDetail, ErrorDetail, FlungConnectEventMap, LoadDetail } from './element/events.js';
+export * from './core/index.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * `@flung.dev/connect`: `<flung-connect>`, a panel that lets people connect and disconnect their social accounts
+ * from your page, with a connect token your server makes. `import '@flung.dev/connect/register'` to register it,
+ * or call `defineFlungConnect()`.
+ */
+export { defineFlungConnect, TAG_NAME } from './element/define.js';
+export { DEFAULT_LABELS } from './element/copy.js';
+export * from './core/index.js';

package/dist/react/index.d.ts

@@ -0,0 +1,30 @@
+import type { CSSProperties } from 'react';
+import type { TokenSource } from '../core/client.js';
+import type { Platform } from '../core/types.js';
+import type { ConnectLabels } from '../element/copy.js';
+import type { ConnectDetail, DisconnectDetail, ErrorDetail, LoadDetail } from '../element/events.js';
+import type { FlungConnectElement } from '../element/flung-connect.js';
+/**
+ * `<FlungConnect>`: the `<flung-connect>` element for React. It registers the element on first render, passes plain
+ * values as attributes, sets `token` and `labels` as properties, and turns the element's events into callbacks. React
+ * is a peer dependency; nothing else is imported. The ref is the element itself, with `refresh()`.
+ */
+export interface FlungConnectProps {
+    /** A connect token from your server, or a function that fetches a fresh one. */
+    token: TokenSource | null;
+    /** Where the API lives; production when left out. */
+    baseUrl?: string | undefined;
+    /** Offer only these platforms. */
+    platforms?: readonly Platform[] | undefined;
+    /** `redirect` sends the whole page to the platform and back, for pages that cannot open windows. */
+    mode?: 'popup' | 'redirect' | undefined;
+    theme?: 'light' | 'dark' | undefined;
+    labels?: Partial<ConnectLabels> | undefined;
+    className?: string | undefined;
+    style?: CSSProperties | undefined;
+    onLoad?: ((detail: LoadDetail) => void) | undefined;
+    onConnect?: ((detail: ConnectDetail) => void) | undefined;
+    onDisconnect?: ((detail: DisconnectDetail) => void) | undefined;
+    onError?: ((detail: ErrorDetail) => void) | undefined;
+}
+export declare const FlungConnect: import("react").ForwardRefExoticComponent<FlungConnectProps & import("react").RefAttributes<FlungConnectElement>>;

package/dist/react/index.js

@@ -0,0 +1,49 @@
+import { createElement, forwardRef, useEffect, useImperativeHandle, useLayoutEffect, useRef } from 'react';
+import { defineFlungConnect, TAG_NAME } from '../element/define.js';
+const EVENTS = { 'flung-load': 'onLoad', 'flung-connect': 'onConnect', 'flung-disconnect': 'onDisconnect', 'flung-error': 'onError' };
+const useClientLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+function FlungConnectInner(props, ref) {
+    const element = useRef(null);
+    const latest = useRef(props);
+    latest.current = props;
+    useImperativeHandle(ref, () => element.current, []);
+    useClientLayoutEffect(() => {
+        defineFlungConnect();
+    }, []);
+    // Listens before the token is handed over below, so the first `flung-load` is not missed.
+    useClientLayoutEffect(() => {
+        const node = element.current;
+        if (node === null)
+            return undefined;
+        const listeners = Object.entries(EVENTS).map(([type, prop]) => {
+            const listener = (event) => {
+                const handler = latest.current[prop];
+                handler?.(event.detail);
+            };
+            node.addEventListener(type, listener);
+            return () => node.removeEventListener(type, listener);
+        });
+        return () => {
+            for (const remove of listeners)
+                remove();
+        };
+    }, []);
+    useClientLayoutEffect(() => {
+        const node = element.current;
+        if (node === null)
+            return;
+        node.labels = props.labels;
+        if (node.token !== props.token)
+            node.token = props.token;
+    }, [props.token, props.labels]);
+    return createElement(TAG_NAME, {
+        ref: element,
+        'base-url': props.baseUrl,
+        platforms: props.platforms?.join(','),
+        mode: props.mode,
+        theme: props.theme,
+        class: props.className,
+        style: props.style,
+    });
+}
+export const FlungConnect = forwardRef(FlungConnectInner);

package/dist/register.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/register.js

@@ -0,0 +1,7 @@
+/**
+ * The side-effect entry: `import '@flung.dev/connect/register'` registers `<flung-connect>`. It is the only module
+ * of the package with a side effect, and `sideEffects` in package.json names it, so a bundler keeps it and tree-shakes
+ * the rest.
+ */
+import { defineFlungConnect } from './element/define.js';
+defineFlungConnect();

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@flung.dev/connect",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Let people connect and disconnect their social accounts from your page: a <flung-connect> web component and a React component for Flung, with no runtime dependencies.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://flung.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flung-official/flung-sdk.git",
+    "directory": "packages/connect"
+  },
+  "keywords": [
+    "flung",
+    "social-media",
+    "oauth",
+    "connect",
+    "web-component",
+    "react"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "default": "./dist/register.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/__tests__",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "./dist/register.js"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.2.3",
+    "jsdom": "30.1.1",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }