@sneekin/ui 0.1.2 → 0.2.1

package/README.md

@@ -1,28 +1,11 @@
 # @sneekin/ui
 
-Drop-in **passwordless OTP login** UI for React, powered by [Sneek](https://sneek.in).
+Drop-in passwordless login for React, powered by [Sneek](https://sneek.in).
 
-One component renders the whole two-step flow — *enter your email/mobile → enter the
-code → signed in* — over SMS, WhatsApp, or email. No passwords.
-
-## The security model (read this first)
-
-`@sneekin/ui` runs in the browser, so it **never holds a Sneek API key**. Instead it
-calls **your own backend**, and your backend calls Sneek server-side with your secret
-key (using [`@sneekin/sdk`](../../sdk)).
-
-```
-Browser (@sneekin/ui)
-   │  POST /api/auth/request-otp { identifier }
-   ▼
-Your backend  ──(@sneekin/sdk, secret key)──►  Sneek API  ──►  SMS / WhatsApp / Email
-   │  POST /api/auth/verify-otp { requestId, code }
-   ▼
-Your backend issues your session / token
-```
-
-Putting a Sneek key in front-end code would expose it to every visitor. This package
-is designed so that can't happen.
+- **No API key in the browser.** The component calls handlers you supply, which talk to your own backend.
+- **No dependencies, no stylesheet to import.** One `<style>` element is injected at runtime.
+- **Light and dark**, following the visitor's system setting by default.
+- **Accessible**: labelled inputs, a polite live region for status, and a visible focus ring on every control.
 
 ## Install
 
@@ -30,123 +13,91 @@ is designed so that can't happen.
 npm install @sneekin/ui
 ```
 
-`react >= 17` is a peer dependency.
+React 17 or newer, as a peer dependency.
 
-## Quick start
+## Use it
 
 ```tsx
 import { SneekOtpLogin, createFetchHandlers } from '@sneekin/ui';
 
-export function LoginPage() {
+export function Login() {
   return (
     <SneekOtpLogin
-      title="Sign in to ConfHub"
-      {...createFetchHandlers({
-        requestUrl: '/api/auth/request-otp',
-        verifyUrl: '/api/auth/verify-otp',
-      })}
-      onSuccess={() => {
-        window.location.href = '/dashboard';
-      }}
+      {...createFetchHandlers({ baseUrl: '/api/auth' })}
+      onSuccess={(session) => router.push('/app')}
     />
   );
 }
 ```
 
-That's the whole front end. `createFetchHandlers` POSTs to your endpoints; defaults are
-`/api/auth/request-otp` and `/api/auth/verify-otp`.
+`createFetchHandlers` expects two routes on **your** server:
 
-### Your backend endpoints
+| Route | Body | Returns |
+| --- | --- | --- |
+| `POST {baseUrl}/request-otp` | `{ identifier }` | `{ requestId, channels, expiresInSeconds }` |
+| `POST {baseUrl}/verify-otp` | `{ requestId, code }` | whatever your session payload is |
 
-```ts
-// POST /api/auth/request-otp   body: { identifier }
-import { Sneek } from '@sneekin/sdk';
-const sneek = new Sneek({ apiKey: process.env.SNEEK_API_KEY! });
+Your server holds the Sneek API key and calls Sneek. The browser never sees it.
 
-const otp = await sneek.sendOTP({ to: identifier, channel: 'auto' });
-return { requestId: otp.id, channels: [otp.channel], expiresInSeconds: 300 };
+## Theming
 
-// POST /api/auth/verify-otp   body: { requestId, code }
-// verify against your store, then return your own session/token
-```
-
-> The exact verify call depends on how you persist the OTP request. Sneek returns a
-> message id on send; store it keyed by `requestId` and check the code your way, or use
-> Sneek's verify endpoint if enabled for your app.
-
-## Headless usage
-
-Want your own markup? Use the hook:
+It follows the system colour scheme out of the box. Pin it if you prefer:
 
 ```tsx
-import { useSneekOtp, createFetchHandlers } from '@sneekin/ui';
+<SneekOtpLogin theme="dark" {...handlers} />
+```
 
-function MyLogin() {
-  const otp = useSneekOtp({
-    ...createFetchHandlers(),
-    onSuccess: (user) => console.log('signed in', user),
-  });
-
-  if (otp.step === 'identify') {
-    return (
-      <form onSubmit={(e) => { e.preventDefault(); otp.sendOtp(); }}>
-        <input value={otp.identifier} onChange={(e) => otp.setIdentifier(e.target.value)} />
-        <button disabled={otp.isBusy}>{otp.isSending ? 'Sending…' : 'Send code'}</button>
-        {otp.error && <p>{otp.error}</p>}
-      </form>
-    );
-  }
+Override the single accent colour — everything else derives from it:
 
-  return (
-    <form onSubmit={(e) => { e.preventDefault(); otp.verify(); }}>
-      <input value={otp.code} onChange={(e) => otp.setCode(e.target.value)} />
-      <button disabled={otp.isBusy}>{otp.isVerifying ? 'Verifying…' : 'Verify'}</button>
-      <button type="button" onClick={otp.back}>Back</button>
-      <button type="button" onClick={otp.resend}>Resend</button>
-    </form>
-  );
-}
+```tsx
+<SneekOtpLogin accentColor="#7c3aed" {...handlers} />
 ```
 
-### Custom transport
-
-Don't want `fetch`? Provide `requestOtp` / `verifyOtp` directly:
+Swap the mark, drop the sub-heading, or remove the Sneek line:
 
 ```tsx
-useSneekOtp({
-  requestOtp: async (identifier) => {
-    const r = await myClient.sendOtp(identifier);
-    return { requestId: r.id, channels: r.channels, expiresInSeconds: r.ttl };
-  },
-  verifyOtp: async ({ requestId, code }) => myClient.verify(requestId, code),
-  onSuccess: (result) => {/* … */},
-});
+<SneekOtpLogin
+  logo={<MyLogo />}
+  subtitle={null}
+  showBranding={false}
+  {...handlers}
+/>
 ```
 
-## API
+For anything further, `className` and `style` land on the outer card, and every
+control carries a stable class (`.sneek-otp-input`, `.sneek-otp-button`,
+`.sneek-otp-link`) you can target.
 
-### `<SneekOtpLogin />`
+## Props
 
-| Prop | Type | Default | Notes |
-| --- | --- | --- | --- |
-| `requestOtp` | `(id) => Promise<RequestOtpResult>` | — | Required |
-| `verifyOtp` | `({requestId, code}) => Promise<T>` | — | Required |
-| `onSuccess` | `(result: T) => void` | — | After verify |
-| `onError` | `(error: unknown) => void` | — | Any failure |
-| `title` | `string` | `'Sign in'` | |
-| `subtitle` | `ReactNode` | Sneek tagline | |
-| `accentColor` | `string` | `'#56d3b5'` | Button colour |
-| `logo` | `ReactNode` | — | Above the title |
-| `style` / `className` | — | — | Container overrides |
+| Prop | Type | Default |
+| --- | --- | --- |
+| `requestOtp` | `(identifier) => Promise<RequestOtpResult>` | — (required) |
+| `verifyOtp` | `(requestId, code) => Promise<TResult>` | — (required) |
+| `onSuccess` | `(result: TResult) => void` | — |
+| `title` | `string` | `'Sign in'` |
+| `subtitle` | `ReactNode \| null` | `'We will send you a one-time code.'` |
+| `identifierLabel` | `string` | `'Email or mobile'` |
+| `identifierPlaceholder` | `string` | `'you@company.com or +91…'` |
+| `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` |
+| `accentColor` | `string` | Sneek orange, tuned per mode |
+| `logo` | `ReactNode \| null` | Sneek mark |
+| `showBranding` | `boolean` | `true` |
+| `className` / `style` | — | — |
 
-`createFetchHandlers(options)` returns `{ requestOtp, verifyOtp }`, so spread it into the
-component or hook.
+## Bring your own markup
 
-### `useSneekOtp(handlers)`
+If the card does not suit you, use the hook and render whatever you like. It
+holds the whole state machine — step, busy flags, errors, resend:
 
-Returns the reducer state plus `setIdentifier`, `setCode`, `sendOtp`, `verify`, `back`,
-`resend`, and the booleans `isSending`, `isVerifying`, `isBusy`.
+```tsx
+import { useSneekOtp, createFetchHandlers } from '@sneekin/ui';
+
+const otp = useSneekOtp(createFetchHandlers({ baseUrl: '/api/auth' }));
+// otp.step, otp.identifier, otp.code, otp.error,
+// otp.sendOtp(), otp.verify(), otp.resend(), otp.back()
+```
 
 ## License
 
-UNLICENSED — © Sneek.
+UNLICENSED — © Abblor Tech Pvt Ltd.

package/dist/component.d.ts

@@ -0,0 +1,49 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import { type SneekOtpHandlers } from './use-sneek-otp';
+export type SneekTheme = 'auto' | 'light' | 'dark';
+export interface SneekOtpLoginProps<TResult = unknown> extends SneekOtpHandlers<TResult> {
+    /** Heading above the form. @default 'Sign in' */
+    title?: string;
+    /** Heading once the code has been sent. @default 'Enter the code' */
+    verifyTitle?: string;
+    /** Sub-heading. Pass `null` to remove it. */
+    subtitle?: ReactNode;
+    /** Label for the identifier input. */
+    identifierLabel?: string;
+    /** Placeholder for the identifier input. */
+    identifierPlaceholder?: string;
+    /**
+     * Colour scheme. `auto` follows the visitor's system setting.
+     * @default 'auto'
+     */
+    theme?: SneekTheme;
+    /**
+     * Override the single accent colour. Leave unset to use Sneek orange,
+     * which is tuned per mode for contrast.
+     */
+    accentColor?: string;
+    /** Replaces the Sneek mark above the title. Pass `null` to remove it. */
+    logo?: ReactNode;
+    /** Show the "Secured by Sneek" line under the form. @default true */
+    showBranding?: boolean;
+    /** Style overrides for the outer card. */
+    style?: CSSProperties;
+    /** Extra class on the outer card. */
+    className?: string;
+}
+/**
+ * Drop-in passwordless login card.
+ *
+ * The component never receives a Sneek API key — it calls the handlers you
+ * supply, which talk to your own backend. See `createFetchHandlers` for the
+ * common case.
+ *
+ * @example
+ * ```tsx
+ * <SneekOtpLogin
+ *   {...createFetchHandlers({ baseUrl: '/api/auth' })}
+ *   onSuccess={(session) => router.push('/app')}
+ * />
+ * ```
+ */
+export declare function SneekOtpLogin<TResult = unknown>(props: SneekOtpLoginProps<TResult>): ReactNode;

package/dist/fetch-handlers.d.ts

@@ -0,0 +1,30 @@
+import type { RequestOtpResult } from './state';
+export interface FetchHandlerOptions {
+    /**
+     * Partner backend endpoint that sends an OTP. Receives `{ identifier }`,
+     * must return `{ requestId, channels?, expiresInSeconds? }`.
+     * @default '/api/auth/request-otp'
+     */
+    requestUrl?: string;
+    /**
+     * Partner backend endpoint that verifies an OTP. Receives
+     * `{ requestId, code }`, returns whatever your app needs (session, token…).
+     * @default '/api/auth/verify-otp'
+     */
+    verifyUrl?: string;
+    /** Extra headers (e.g. CSRF token) to send on both requests. */
+    headers?: Record<string, string>;
+    /** Forwarded to fetch — set to 'include' if you use cookie sessions. */
+    credentials?: RequestCredentials;
+}
+/**
+ * Build {@link SneekOtpHandlers} that POST to your own backend endpoints.
+ * Those endpoints call the Sneek API server-side with your secret key.
+ */
+export declare function createFetchHandlers<TResult = unknown>(options?: FetchHandlerOptions): {
+    requestOtp: (identifier: string) => Promise<RequestOtpResult>;
+    verifyOtp: (input: {
+        requestId: string;
+        code: string;
+    }) => Promise<TResult>;
+};

package/dist/index.d.ts

@@ -1,160 +1,5 @@
-import { ReactNode, CSSProperties } from 'react';
-
-/**
- * Framework-agnostic state machine for the Sneek passwordless OTP flow.
- *
- * Kept free of React so it can be unit-tested in isolation and reused by other
- * front-end bindings later (Vue/Svelte). The hook in `use-sneek-otp.ts` is a
- * thin wrapper around this reducer.
- */
-type SneekChannel = 'sms' | 'whatsapp' | 'email';
-/** Which screen of the two-step flow is showing. */
-type SneekOtpStep = 'identify' | 'verify';
-/** Async lifecycle for the in-flight request. */
-type SneekOtpStatus = 'idle' | 'sending' | 'verifying';
-interface SneekOtpState {
-    step: SneekOtpStep;
-    status: SneekOtpStatus;
-    /** The email / mobile / username the user typed. */
-    identifier: string;
-    /** The OTP code the user typed on the verify screen. */
-    code: string;
-    /** Opaque id returned by the partner backend, replayed on verify. */
-    requestId: string;
-    /** Channels the OTP was actually delivered over. */
-    channels: SneekChannel[];
-    /** Seconds until the OTP expires (from the request response). */
-    expiresInSeconds: number;
-    /** User-facing error message, or null. */
-    error: string | null;
-}
-declare const initialOtpState: SneekOtpState;
-interface RequestOtpResult {
-    requestId: string;
-    channels?: SneekChannel[];
-    expiresInSeconds?: number;
-}
-type SneekOtpAction = {
-    type: 'set_identifier';
-    value: string;
-} | {
-    type: 'set_code';
-    value: string;
-} | {
-    type: 'request_start';
-} | {
-    type: 'request_success';
-    result: RequestOtpResult;
-} | {
-    type: 'request_error';
-    message: string;
-} | {
-    type: 'verify_start';
-} | {
-    type: 'verify_error';
-    message: string;
-} | {
-    type: 'reset';
-} | {
-    type: 'back_to_identify';
-};
-declare function otpReducer(state: SneekOtpState, action: SneekOtpAction): SneekOtpState;
-/** "SMS, WhatsApp" — human label for the channels an OTP was sent over. */
-declare function formatChannels(channels: SneekChannel[]): string;
-
-/**
- * Partner-supplied transport. These call the *partner's own backend*, which in
- * turn talks to the Sneek API with the secret server-side key. The browser
- * never sees a Sneek API key — that is the whole security model of this package.
- */
-interface SneekOtpHandlers<TResult = unknown> {
-    /** Ask the partner backend to send an OTP to `identifier`. */
-    requestOtp: (identifier: string) => Promise<RequestOtpResult>;
-    /** Verify the code with the partner backend; resolve with the auth result. */
-    verifyOtp: (input: {
-        requestId: string;
-        code: string;
-    }) => Promise<TResult>;
-    /** Called after a successful verification with the partner's result. */
-    onSuccess?: (result: TResult) => void;
-    /** Called on any error (request or verify). */
-    onError?: (error: unknown) => void;
-}
-interface UseSneekOtp extends SneekOtpState {
-    setIdentifier: (value: string) => void;
-    setCode: (value: string) => void;
-    /** Submit the identify step — triggers `requestOtp`. */
-    sendOtp: () => Promise<void>;
-    /** Submit the verify step — triggers `verifyOtp`. */
-    verify: () => Promise<void>;
-    /** Go back to the identify screen (e.g. "use a different email"). */
-    back: () => void;
-    /** Re-send the OTP to the same identifier. */
-    resend: () => Promise<void>;
-    /** Convenience booleans. */
-    isSending: boolean;
-    isVerifying: boolean;
-    isBusy: boolean;
-}
-/**
- * Headless hook implementing the passwordless OTP login flow. Bring your own
- * markup, or use the {@link SneekOtpLogin} component for a styled default.
- */
-declare function useSneekOtp<TResult = unknown>(handlers: SneekOtpHandlers<TResult>): UseSneekOtp;
-
-interface SneekOtpLoginProps<TResult = unknown> extends SneekOtpHandlers<TResult> {
-    /** Heading shown above the form. @default 'Sign in' */
-    title?: string;
-    /** Sub-heading. @default 'Passwordless login powered by Sneek' */
-    subtitle?: ReactNode;
-    /** Label for the identifier input. */
-    identifierLabel?: string;
-    /** Placeholder for the identifier input. */
-    identifierPlaceholder?: string;
-    /** Brand colour for the primary button. @default '#56d3b5' */
-    accentColor?: string;
-    /** Optional logo rendered above the title. */
-    logo?: ReactNode;
-    /** Override the outer container style. */
-    style?: CSSProperties;
-    /** Extra className on the outer container. */
-    className?: string;
-}
-/**
- * Drop-in, dependency-free passwordless OTP login card. The component never
- * receives a Sneek API key; it calls the partner-supplied handlers, which talk
- * to the partner backend. Use {@link createFetchHandlers} for the common case.
- */
-declare function SneekOtpLogin<TResult = unknown>(props: SneekOtpLoginProps<TResult>): ReactNode;
-
-interface FetchHandlerOptions {
-    /**
-     * Partner backend endpoint that sends an OTP. Receives `{ identifier }`,
-     * must return `{ requestId, channels?, expiresInSeconds? }`.
-     * @default '/api/auth/request-otp'
-     */
-    requestUrl?: string;
-    /**
-     * Partner backend endpoint that verifies an OTP. Receives
-     * `{ requestId, code }`, returns whatever your app needs (session, token…).
-     * @default '/api/auth/verify-otp'
-     */
-    verifyUrl?: string;
-    /** Extra headers (e.g. CSRF token) to send on both requests. */
-    headers?: Record<string, string>;
-    /** Forwarded to fetch — set to 'include' if you use cookie sessions. */
-    credentials?: RequestCredentials;
-}
-/**
- * Build {@link SneekOtpHandlers} that POST to your own backend endpoints.
- * Those endpoints call the Sneek API server-side with your secret key.
- */
-declare function createFetchHandlers<TResult = unknown>(options?: FetchHandlerOptions): {
-    requestOtp: (identifier: string) => Promise<RequestOtpResult>;
-    verifyOtp: (input: {
-        requestId: string;
-        code: string;
-    }) => Promise<TResult>;
-};
-
-export { type FetchHandlerOptions, type RequestOtpResult, type SneekChannel, type SneekOtpAction, type SneekOtpHandlers, SneekOtpLogin, type SneekOtpLoginProps, type SneekOtpState, type SneekOtpStatus, type SneekOtpStep, type UseSneekOtp, createFetchHandlers, formatChannels, initialOtpState, otpReducer, useSneekOtp };
+export { useSneekOtp, type SneekOtpHandlers, type UseSneekOtp, } from './use-sneek-otp';
+export { SneekOtpLogin, type SneekOtpLoginProps, type SneekTheme, } from './component';
+export { SNEEK_ACCENT_DARK, SNEEK_ACCENT_LIGHT, } from './theme';
+export { createFetchHandlers, type FetchHandlerOptions, } from './fetch-handlers';
+export { otpReducer, initialOtpState, formatChannels, type SneekChannel, type SneekOtpStep, type SneekOtpStatus, type SneekOtpState, type SneekOtpAction, type RequestOtpResult, } from './state';