@phosra/connect 0.1.0

package/src/core/types.ts

@@ -0,0 +1,122 @@
+// Wire contract for the Phosra Connect component. These types mirror the
+// client-facing shapes of @phosra/link's server-side ceremony, but are defined
+// LOCALLY so this package has zero server dependencies (no @phosra/link runtime,
+// no pg). The PCA app implements a BFF that fulfils `ConnectTransport` by calling
+// @phosra/link server-side (initPlatformOAuth / completePlatformOAuth / bindProfile
+// / runConnectCeremony).
+
+export type AgeHint = 'under_13' | '13_15' | '16_17';
+
+/** A child account discovered on the platform after the parent authorizes. */
+export interface ChildProfile {
+  id: string;
+  displayName: string;
+  ageHint?: number;
+}
+
+/** One safety rule shown in the pre-connect preview ("what Snaptr will apply & confirm"). */
+export interface ConnectRule {
+  category: string;
+  label: string;
+}
+
+/** The enforcement platform being connected (e.g. Snaptr). */
+export interface ConnectPlatform {
+  did: string;
+  name: string;
+}
+
+export interface InitResult {
+  authorizeUrl: string;
+  state: string;
+  sessionId: string;
+}
+export interface CompleteResult {
+  sessionId: string;
+  childProfiles: ChildProfile[];
+}
+export interface BindResult {
+  grant_id: string;
+}
+
+/**
+ * The three BFF calls the component drives. The PCA implements these against its
+ * own routes, which wrap @phosra/link server-side. The component NEVER talks to
+ * Phosra directly, and never sees the endpoint_id_label (the server delivers it
+ * to the platform).
+ */
+export interface ConnectTransport {
+  init(req: {
+    platformDid: string;
+    childId?: string;
+    grantedScope: string[];
+    ageHint?: AgeHint;
+  }): Promise<InitResult>;
+  complete(req: { code: string; state: string; sessionId: string }): Promise<CompleteResult>;
+  bind(req: {
+    sessionId: string;
+    platformChildProfileId: string;
+    childId: string;
+    grantedScope: string[];
+    ageHint?: AgeHint;
+  }): Promise<BindResult>;
+}
+
+/**
+ * Injected per-platform. Opens the secure webview to `authorizeUrl` and resolves
+ * the redirect's `{code, state}` (or `{canceled:true}` if the parent backs out).
+ * Web supplies a popup/postMessage opener; React Native supplies an
+ * expo-web-browser opener. The core is platform-agnostic because this is injected.
+ */
+export type AuthorizeOpener = (
+  authorizeUrl: string,
+  redirectUri: string,
+) => Promise<{ code: string; state: string } | { canceled: true }>;
+
+export type ConnectStatus =
+  | 'idle'
+  | 'authorizing'
+  | 'exchanging'
+  | 'selecting'
+  | 'binding'
+  | 'success'
+  | 'error'
+  | 'canceled';
+
+export interface ConnectError {
+  stage: ConnectStatus;
+  message: string;
+}
+
+export interface ConnectState {
+  status: ConnectStatus;
+  childProfiles?: ChildProfile[];
+  result?: BindResult;
+  error?: ConnectError;
+}
+
+export interface ConnectControllerOptions {
+  transport: ConnectTransport;
+  openAuthorizeUrl: AuthorizeOpener;
+  redirectUri: string;
+  platform: ConnectPlatform;
+  grantedScope: string[];
+  childId?: string;
+  ageHint?: AgeHint;
+  onSuccess?(r: BindResult): void;
+  onError?(e: ConnectError): void;
+  onExit?(): void;
+}
+
+export interface ConnectController {
+  getState(): ConnectState;
+  subscribe(fn: (s: ConnectState) => void): () => void;
+  /** Begin the ceremony (from idle / error / canceled). */
+  open(): Promise<void>;
+  /** Confirm the child to bind (valid only while status === 'selecting'). */
+  selectChild(profileId: string): Promise<void>;
+  /** Re-run from the failed stage. */
+  retry(): Promise<void>;
+  /** Abort → canceled, fires onExit. */
+  cancel(): void;
+}

package/src/core/useConnect.ts

@@ -0,0 +1,68 @@
+import { useRef, useSyncExternalStore } from 'react';
+import { createConnectController } from './controller.js';
+import type { ConnectController, ConnectControllerOptions, ConnectState } from './types.js';
+
+export interface UseConnectResult {
+  state: ConnectState;
+  open: ConnectController['open'];
+  selectChild: ConnectController['selectChild'];
+  retry: ConnectController['retry'];
+  cancel: ConnectController['cancel'];
+}
+
+/**
+ * Universal React hook wrapping the framework-agnostic ConnectController. Works
+ * on web and React Native (it imports only `react`, never `react-dom` or
+ * `react-native`). The controller is created once; option changes (fresh
+ * callbacks, transport, scope) are picked up lazily via a ref, so the controller
+ * identity — and therefore any in-flight ceremony — is stable across renders.
+ */
+export function useConnect(opts: ConnectControllerOptions): UseConnectResult {
+  const optsRef = useRef(opts);
+  optsRef.current = opts;
+
+  const controllerRef = useRef<ConnectController | null>(null);
+  if (controllerRef.current === null) {
+    controllerRef.current = createConnectController({
+      get transport() {
+        return optsRef.current.transport;
+      },
+      get openAuthorizeUrl() {
+        return optsRef.current.openAuthorizeUrl;
+      },
+      get redirectUri() {
+        return optsRef.current.redirectUri;
+      },
+      get platform() {
+        return optsRef.current.platform;
+      },
+      get grantedScope() {
+        return optsRef.current.grantedScope;
+      },
+      get childId() {
+        return optsRef.current.childId;
+      },
+      get ageHint() {
+        return optsRef.current.ageHint;
+      },
+      onSuccess: (r) => optsRef.current.onSuccess?.(r),
+      onError: (e) => optsRef.current.onError?.(e),
+      onExit: () => optsRef.current.onExit?.(),
+    });
+  }
+  const controller = controllerRef.current;
+
+  const state = useSyncExternalStore(
+    controller.subscribe,
+    controller.getState,
+    controller.getState,
+  );
+
+  return {
+    state,
+    open: controller.open,
+    selectChild: controller.selectChild,
+    retry: controller.retry,
+    cancel: controller.cancel,
+  };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+// Default entry = core + web (the common case: a web PCA using the styled
+// drop-in). React Native consumers import from '@phosra/connect/native'.
+export * from './core/index.js';
+export * from './web/index.js';

package/src/native/ConnectFlow.native.tsx

@@ -0,0 +1,205 @@
+/**
+ * ConnectFlow (React Native) — unstyled reference implementation. Mirrors
+ * web/ConnectFlow.tsx: same states, same honest copy, minimal styling, semantic
+ * structure with stable `accessibilityHint` hooks so a PCA can style it entirely.
+ *
+ * This is the "Layer 2" starting point between the headless hook (useConnect)
+ * and the styled drop-in (PhosraConnect.native.tsx). The honesty contract copy
+ * ("never a fake green") is preserved; only visual treatment is left to the
+ * consumer.
+ */
+import * as React from 'react';
+import { View, Text, Pressable } from 'react-native';
+import { useConnect } from '../core/useConnect.js';
+import type {
+  AgeHint,
+  AuthorizeOpener,
+  BindResult,
+  ConnectError,
+  ConnectPlatform,
+  ConnectRule,
+  ConnectTransport,
+} from '../core/types.js';
+import { createNativeAuthorizeOpener } from './openAuthorizeUrl.native.js';
+
+export interface ConnectFlowProps {
+  platform: ConnectPlatform;
+  rules: ConnectRule[];
+  grantedScope: string[];
+  transport: ConnectTransport;
+  redirectUri: string;
+  childId?: string;
+  ageHint?: AgeHint;
+  openAuthorizeUrl?: AuthorizeOpener;
+  onSuccess?(r: BindResult): void;
+  onError?(e: ConnectError): void;
+  onExit?(): void;
+}
+
+export function ConnectFlow(props: ConnectFlowProps): React.ReactElement {
+  const opener = React.useMemo(
+    () => props.openAuthorizeUrl ?? createNativeAuthorizeOpener(),
+    [props.openAuthorizeUrl],
+  );
+  const { state, open, selectChild, retry, cancel } = useConnect({
+    transport: props.transport,
+    openAuthorizeUrl: opener,
+    redirectUri: props.redirectUri,
+    platform: props.platform,
+    grantedScope: props.grantedScope,
+    childId: props.childId,
+    ageHint: props.ageHint,
+    onSuccess: props.onSuccess,
+    onError: props.onError,
+    onExit: props.onExit,
+  });
+  const [showRules, setShowRules] = React.useState(false);
+  const { status } = state;
+  const name = props.platform.name;
+
+  if (status === 'idle' && !showRules) {
+    return (
+      <View accessibilityHint="phosra-connect-intro">
+        <Text accessibilityHint="phosra-connect-title">Connect {name}</Text>
+        <Text accessibilityHint="phosra-connect-subtitle">
+          {'You\'ll go to '}{name}{' to securely approve these safety rules for your child\'s account.'}
+        </Text>
+        <Text accessibilityHint="phosra-connect-trust">Accredited on the OCSS Trust List.</Text>
+        <Text accessibilityHint="phosra-connect-footnote">
+          {'Phosra verifies enforcement with '}{name}{' and can\'t read messages.'}
+        </Text>
+        <Pressable
+          accessibilityHint="phosra-connect-continue"
+          accessibilityRole="button"
+          onPress={() => setShowRules(true)}
+        >
+          <Text>Continue</Text>
+        </Pressable>
+      </View>
+    );
+  }
+
+  if (status === 'idle' && showRules) {
+    return (
+      <View accessibilityHint="phosra-connect-rules">
+        <Text accessibilityHint="phosra-connect-title">Connect {name}</Text>
+        <Text accessibilityHint="phosra-connect-subtitle">
+          {'After you connect, '}{name}{' applies and confirms these rules:'}
+        </Text>
+        <View accessibilityHint="phosra-connect-rule-list">
+          {props.rules.map((rule) => (
+            <View key={rule.category} accessibilityHint={`phosra-connect-rule-${rule.category}`}>
+              <Text>{rule.label}</Text>
+            </View>
+          ))}
+        </View>
+        <Text accessibilityHint="phosra-connect-footnote">
+          {'Shown as "Enforced" only after '}{name}{' confirms — never a fake green.'}
+        </Text>
+        <Pressable
+          accessibilityHint="phosra-connect-back"
+          accessibilityRole="button"
+          onPress={() => setShowRules(false)}
+        >
+          <Text>Back</Text>
+        </Pressable>
+        <Pressable
+          accessibilityHint="phosra-connect-continue"
+          accessibilityRole="button"
+          onPress={() => void open()}
+        >
+          <Text>Continue</Text>
+        </Pressable>
+      </View>
+    );
+  }
+
+  if (status === 'authorizing' || status === 'exchanging') {
+    return (
+      <View accessibilityHint="phosra-connect-loading" accessibilityLabel="Loading">
+        <Text>
+          {status === 'authorizing' ? `Waiting for ${name}…` : 'Finishing up…'}
+        </Text>
+      </View>
+    );
+  }
+
+  if (status === 'selecting') {
+    return (
+      <View accessibilityHint="phosra-connect-picker">
+        <Text accessibilityHint="phosra-connect-title">Choose an account</Text>
+        <Text accessibilityHint="phosra-connect-subtitle">
+          {'Which '}{name}{' account should these rules protect?'}
+        </Text>
+        <View accessibilityHint="phosra-connect-profile-list">
+          {(state.childProfiles ?? []).map((profile) => (
+            <Pressable
+              key={profile.id}
+              accessibilityHint={`phosra-connect-profile-${profile.id}`}
+              accessibilityRole="button"
+              onPress={() => void selectChild(profile.id)}
+            >
+              <Text>{profile.displayName}</Text>
+            </Pressable>
+          ))}
+        </View>
+      </View>
+    );
+  }
+
+  if (status === 'binding') {
+    return (
+      <View accessibilityHint="phosra-connect-loading" accessibilityLabel="Applying rules">
+        <Text>Applying rules on {name}…</Text>
+      </View>
+    );
+  }
+
+  if (status === 'success') {
+    return (
+      <View accessibilityHint="phosra-connect-success">
+        <Text accessibilityHint="phosra-connect-title">{name} connected</Text>
+        <Text accessibilityHint="phosra-connect-subtitle">
+          {'These rules are now enforced on '}{name}{'.'}
+        </Text>
+        <Text accessibilityHint="phosra-connect-verified">Verified on the OCSS Trust List.</Text>
+        <Pressable
+          accessibilityHint="phosra-connect-done"
+          accessibilityRole="button"
+          onPress={() => props.onExit?.()}
+        >
+          <Text>Done</Text>
+        </Pressable>
+      </View>
+    );
+  }
+
+  if (status === 'error') {
+    return (
+      <View accessibilityHint="phosra-connect-error" accessibilityRole="alert" accessibilityLiveRegion="polite">
+        <Text accessibilityHint="phosra-connect-title">
+          {'Couldn\'t connect '}{name}
+        </Text>
+        <Text accessibilityHint="phosra-connect-error-message">
+          {state.error?.message ?? 'Something went wrong.'}{' No rules were changed — you can try again.'}
+        </Text>
+        <Pressable
+          accessibilityHint="phosra-connect-retry"
+          accessibilityRole="button"
+          onPress={() => void retry()}
+        >
+          <Text>Try again</Text>
+        </Pressable>
+        <Pressable
+          accessibilityHint="phosra-connect-cancel"
+          accessibilityRole="button"
+          onPress={() => cancel()}
+        >
+          <Text>Cancel</Text>
+        </Pressable>
+      </View>
+    );
+  }
+
+  return <View accessibilityHint="phosra-connect-canceled" />;
+}