@ateam-ai-mobile/core 0.1.0 → 0.1.1

package/src/acs/api.ts

@@ -0,0 +1,345 @@
+/**
+ * Client for Core's /api/acs/* proxy → ACS service. Powers the "widgets"
+ * surface on home: AI-generated artifacts that render as carousel tiles and
+ * full-screen interactive panels via the bundleUrl — plus the home
+ * "top actions" feed.
+ *
+ * Endpoints:
+ *   POST   /api/acs/surface           — list active artifacts for a surface
+ *   POST   /api/acs/event             — usage tracking (clicked/dismissed/etc.)
+ *   GET    /api/acs/made-for-you      — full library, all lifecycle stages
+ *   DELETE /api/acs/artifacts/{id}    — user-initiated retire (idempotent)
+ *   PATCH  /api/acs/artifacts/{id}    — visibility + rename
+ *   PUT    /api/acs/order             — drag-reorder
+ *   GET    /api/acs/home-actions      — top-actions feed (+ PATCH/PUT order)
+ *   WS topics acs.artifacts / acs.home-actions — cross-device sync (see ./ws)
+ */
+
+import { getCoreApiUrl, getToken } from '../config';
+import { reportAcsServerUp, reportAcsServerDown } from './providers';
+
+export interface AcsArtifact {
+  id: string;
+  name: string;
+  description?: string;
+  iconHint?: string;
+  manifest?: Record<string, any>;
+  bundleUrl: string;
+  version: number;
+  provenance?: Record<string, any>;
+
+  // Tile-shape fields (consumers branch on these when present; safe defaults
+  // when absent).
+  kind?: 'user' | 'featured';
+  visibility?: 'pinned' | 'hidden';
+  pinOrder?: number;
+  canDelete?: boolean;
+  canRename?: boolean;
+  canHide?: boolean;
+  previewMode?: 'live' | 'snapshot' | 'none';
+  previewUrl?: string;
+}
+
+// Closed-ish enum — accept arbitrary strings so the backend can introduce new
+// surface names without a client release blocking it.
+export type AcsSurface = 'home' | 'library' | (string & {});
+
+// Closed enum on the backend side.
+export type AcsEvent = 'clicked' | 'dismissed' | 'acted' | 'ignored';
+
+export type AcsDeleteReason =
+  | 'user_long_press_delete'
+  | 'user_swipe_delete'
+  | 'user_bulk_delete'
+  | (string & {});
+
+export type AcsPatchReason =
+  | 'user_long_press_hide'
+  | 'user_long_press_unhide'
+  | 'user_long_press_rename'
+  | (string & {});
+
+async function authedFetch(path: string, init?: RequestInit): Promise<Response> {
+  const token = getToken();
+  try {
+    const res = await fetch(`${getCoreApiUrl()}${path}`, {
+      ...init,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        ...(init?.headers || {}),
+      },
+    });
+    // Any response (even 4xx/5xx) proves the server is reachable.
+    reportAcsServerUp();
+    return res;
+  } catch (e) {
+    // Thrown = network error / timeout / DNS / TLS → server unreachable.
+    reportAcsServerDown();
+    throw e;
+  }
+}
+
+/**
+ * List artifacts surfaced for the given surface name. Returns [] on error
+ * (network, auth, or empty result) — callers shouldn't have to distinguish.
+ * Use surface="home" for the carousel.
+ */
+export async function listSurface(
+  surface: AcsSurface,
+  context?: Record<string, any>,
+): Promise<AcsArtifact[]> {
+  try {
+    const res = await authedFetch('/api/acs/surface', {
+      method: 'POST',
+      body: JSON.stringify({ surface, ...(context ? { context } : {}) }),
+    });
+    if (!res.ok) {
+      console.warn(`[acs] /surface ${surface} returned ${res.status}`);
+      return [];
+    }
+    const data = await res.json();
+    return Array.isArray(data?.items) ? (data.items as AcsArtifact[]) : [];
+  } catch (e: any) {
+    console.warn('[acs] /surface failed:', e?.message || e);
+    return [];
+  }
+}
+
+/**
+ * Full library — every artifact across all lifecycle stages. Used by a
+ * Library screen's Yours + Hidden sections.
+ */
+export async function listMadeForYou(): Promise<AcsArtifact[]> {
+  try {
+    const res = await authedFetch('/api/acs/made-for-you', { method: 'GET' });
+    if (!res.ok) {
+      console.warn(`[acs] /made-for-you returned ${res.status}`);
+      return [];
+    }
+    const data = await res.json();
+    return Array.isArray(data?.artifacts) ? (data.artifacts as AcsArtifact[]) : [];
+  } catch (e: any) {
+    console.warn('[acs] /made-for-you failed:', e?.message || e);
+    return [];
+  }
+}
+
+export interface DeleteResult {
+  ok: boolean;
+  /** True when the server already had this artifact retired. Treat as success. */
+  already?: boolean;
+  /** True for HTTP 404 — artifact gone or never owned by caller. Treat as success
+   *  (remove from local state) per the backend's contract: no existence leak. */
+  notFound?: boolean;
+  /** HTTP status returned by the server. */
+  status: number;
+  error?: string;
+}
+
+/**
+ * Retire a user widget. Per backend contract:
+ *   200 ok                → success
+ *   200 ok + already:true → idempotent, treat as success
+ *   404                   → already gone or not owned, treat as success
+ *   5xx / network         → real failure, caller should rollback optimistic remove
+ */
+export async function deleteArtifact(
+  artifactId: string,
+  reason: AcsDeleteReason = 'user_long_press_delete',
+): Promise<DeleteResult> {
+  try {
+    const res = await authedFetch(
+      `/api/acs/artifacts/${encodeURIComponent(artifactId)}`,
+      { method: 'DELETE', body: JSON.stringify({ reason }) },
+    );
+    const data = await res.json().catch(() => ({} as any));
+    if (res.ok) {
+      return { ok: true, already: !!data?.already, status: res.status };
+    }
+    if (res.status === 404) {
+      return { ok: true, notFound: true, status: 404 };
+    }
+    return { ok: false, status: res.status, error: data?.error || `HTTP ${res.status}` };
+  } catch (e: any) {
+    return { ok: false, status: 0, error: e?.message || 'network error' };
+  }
+}
+
+export interface PatchResult {
+  ok: boolean;
+  /** Updated tile when the server returns the new state. */
+  artifact?: AcsArtifact;
+  already?: boolean;
+  notFound?: boolean;
+  status: number;
+  error?: string;
+}
+
+/**
+ * Update an artifact's visibility (hide/unhide) and/or name (rename). One
+ * call covers both because backend offers a single PATCH endpoint with
+ * optional fields. At least one of visibility/name must be provided.
+ *
+ * Per backend contract (mirrors DELETE semantics):
+ *   200 ok                → success
+ *   200 ok + already:true → idempotent no-op, treat as success
+ *   404                   → not found / not owned, treat as success
+ *   400 / 403             → real failure, surface to user
+ *   5xx / network         → real failure, caller should rollback
+ */
+export async function patchArtifact(
+  artifactId: string,
+  body: { visibility?: 'pinned' | 'hidden'; name?: string },
+  reason: AcsPatchReason,
+): Promise<PatchResult> {
+  try {
+    const res = await authedFetch(
+      `/api/acs/artifacts/${encodeURIComponent(artifactId)}`,
+      { method: 'PATCH', body: JSON.stringify({ ...body, reason }) },
+    );
+    const data = await res.json().catch(() => ({} as any));
+    if (res.ok) {
+      return {
+        ok: true,
+        already: !!data?.already,
+        artifact: data?.artifact || undefined,
+        status: res.status,
+      };
+    }
+    if (res.status === 404) {
+      return { ok: true, notFound: true, status: 404 };
+    }
+    return {
+      ok: false,
+      status: res.status,
+      error: data?.error || `HTTP ${res.status}`,
+    };
+  } catch (e: any) {
+    return { ok: false, status: 0, error: e?.message || 'network error' };
+  }
+}
+
+/**
+ * Persist a new pin order. Body lists currently-pinned artifact IDs in the
+ * new visual order; server validates ownership + pinned state of each ID.
+ *
+ * Returns { ok: false, error } on failure. 400 means the array contained
+ * an id that's not owned or not pinned — caller should refetch /surface
+ * and re-render rather than fight the server.
+ */
+export async function setOrder(pinned: string[]): Promise<{ ok: boolean; status: number; error?: string }> {
+  try {
+    const res = await authedFetch('/api/acs/order', {
+      method: 'PUT',
+      body: JSON.stringify({ pinned }),
+    });
+    if (res.ok) return { ok: true, status: res.status };
+    const data = await res.json().catch(() => ({} as any));
+    return { ok: false, status: res.status, error: data?.error || `HTTP ${res.status}` };
+  } catch (e: any) {
+    return { ok: false, status: 0, error: e?.message || 'network error' };
+  }
+}
+
+/**
+ * Record a usage event. Fire-and-forget — never throws, never blocks the UI.
+ * Use surface to tell the backend which surface the event came from
+ * (e.g. 'home' for the carousel).
+ */
+export async function recordEvent(
+  artifactId: string,
+  event: AcsEvent,
+  surface?: AcsSurface,
+): Promise<void> {
+  try {
+    await authedFetch('/api/acs/event', {
+      method: 'POST',
+      body: JSON.stringify({ artifactId, event, ...(surface ? { surface } : {}) }),
+    });
+  } catch {
+    // intentional swallow — usage tracking failures shouldn't surface to the user
+  }
+}
+
+// ─── Home Actions (top-actions feed) ────────────────────────────────────
+// Server-managed recommended-actions feed for the home "What's on your mind?"
+// screen. The card universe is open + agent-authored; the only fixed contract
+// is this wire shape + the leaf dispatch (send_message | open_widget).
+// Backend: GET /api/acs/home-actions, PUT /order, PATCH /:id,
+// WS topic acs.home-actions.
+
+export type HomeActionLeaf =
+  | { type: 'send_message'; prompt: string; skillSlug?: string }
+  | { type: 'open_widget'; artifactId: string }
+  | { type: string; [k: string]: any }; // forward-compat: open_url/run_tool/…
+
+export interface HomeAction {
+  actionId: string;
+  pinOrder?: number;
+  title: string;
+  subtitle?: string;
+  icon?: string;
+  action: HomeActionLeaf;
+  source?: 'curated' | 'pinned_by_user' | 'skill_authored' | (string & {});
+  canDismiss?: boolean;
+  canPin?: boolean;
+  pinned?: boolean;
+}
+
+/** List the home top-actions feed. Returns [] on any error. */
+export async function listHomeActions(): Promise<HomeAction[]> {
+  try {
+    const res = await authedFetch('/api/acs/home-actions', { method: 'GET' });
+    if (!res.ok) {
+      console.warn(`[acs] /home-actions returned ${res.status}`);
+      return [];
+    }
+    const data = await res.json();
+    return Array.isArray(data?.actions) ? (data.actions as HomeAction[]) : [];
+  } catch (e: any) {
+    console.warn('[acs] /home-actions failed:', e?.message || e);
+    return [];
+  }
+}
+
+export type HomeActionReason =
+  | 'user_pin' | 'user_unpin' | 'user_dismiss' | 'user_drag_reorder'
+  | (string & {});
+
+/** Pin/unpin or dismiss a card. 200 already / 404 both count as success. */
+export async function patchHomeAction(
+  actionId: string,
+  body: { pinned?: boolean; dismissed?: boolean },
+  reason: HomeActionReason,
+): Promise<{ ok: boolean; action?: HomeAction; status: number; error?: string }> {
+  try {
+    const res = await authedFetch(
+      `/api/acs/home-actions/${encodeURIComponent(actionId)}`,
+      { method: 'PATCH', body: JSON.stringify({ ...body, reason }) },
+    );
+    const data = await res.json().catch(() => ({} as any));
+    if (res.ok) return { ok: true, action: data?.action || undefined, status: res.status };
+    if (res.status === 404) return { ok: true, status: 404 };
+    return { ok: false, status: res.status, error: data?.error || `HTTP ${res.status}` };
+  } catch (e: any) {
+    return { ok: false, status: 0, error: e?.message || 'network error' };
+  }
+}
+
+/** Persist a new card order. Optimistic; caller rolls back on failure. */
+export async function setHomeActionOrder(
+  order: string[],
+): Promise<{ ok: boolean; status: number; error?: string }> {
+  try {
+    const res = await authedFetch('/api/acs/home-actions/order', {
+      method: 'PUT',
+      body: JSON.stringify({ order }),
+    });
+    if (res.ok) return { ok: true, status: res.status };
+    const data = await res.json().catch(() => ({} as any));
+    return { ok: false, status: res.status, error: data?.error || `HTTP ${res.status}` };
+  } catch (e: any) {
+    return { ok: false, status: 0, error: e?.message || 'network error' };
+  }
+}

package/src/acs/homeActionsStore.ts

@@ -0,0 +1,178 @@
+/**
+ * The home "What's on your mind?" top-actions feed. Server-managed: the list,
+ * its order, pin and dismiss state all live on the backend (ACS home-actions
+ * API). This store is a thin local mirror with optimistic mutations + rollback
+ * — same discipline as widgetsStore.
+ *
+ * The cards themselves are agent-authored and open-ended; clients only know
+ * the wire shape + the fixed leaf dispatch (send_message | open_widget), so
+ * this store stays dumb on purpose.
+ */
+
+import { create } from 'zustand';
+import {
+  listHomeActions,
+  patchHomeAction,
+  setHomeActionOrder,
+  type HomeAction,
+} from './api';
+import { getAcsCacheStorage } from './providers';
+
+// Persisted (when the host wires setAcsCacheStorage) so the home cards render
+// instantly on cold start and survive a dead/empty server response. The
+// server is still source of truth — when a non-empty result arrives we
+// overwrite the cache; an empty/failed fetch leaves the last good cards on
+// screen.
+const CACHE_KEY = 'ateam.homeActions.v1';
+
+function persist(actions: HomeAction[]): void {
+  // Fire-and-forget; never block the UI on disk.
+  getAcsCacheStorage()?.setItem(CACHE_KEY, JSON.stringify(actions)).catch(() => {});
+}
+
+interface HomeActionsState {
+  actions: HomeAction[];
+  hydrated: boolean;
+  loading: boolean;
+
+  hydrate: () => Promise<void>;
+  refresh: () => Promise<void>;
+  clear: () => void;
+
+  /** Optimistic dismiss — removes locally, rolls back on real failure. */
+  dismiss: (actionId: string) => Promise<{ ok: boolean; error?: string }>;
+  /** Optimistic pin/unpin. */
+  setPinned: (actionId: string, pinned: boolean) => Promise<{ ok: boolean; error?: string }>;
+  /** Optimistic reorder — `orderedIds` is the new visual order. */
+  reorder: (orderedIds: string[]) => Promise<{ ok: boolean; error?: string }>;
+
+  // ─── WS-driven (local mutation only, no API call) ───
+  applyServerUpsert: (action: HomeAction) => void;
+  applyServerRemove: (actionId: string) => void;
+  applyServerOrder: (orderedIds: string[]) => void;
+}
+
+function sortByPin(a: HomeAction, b: HomeAction): number {
+  // pinned first, then pinOrder asc, then stable.
+  if (!!a.pinned !== !!b.pinned) return a.pinned ? -1 : 1;
+  const ao = typeof a.pinOrder === 'number' ? a.pinOrder : Number.MAX_SAFE_INTEGER;
+  const bo = typeof b.pinOrder === 'number' ? b.pinOrder : Number.MAX_SAFE_INTEGER;
+  return ao - bo;
+}
+
+export const useHomeActionsStore = create<HomeActionsState>((set, get) => ({
+  actions: [],
+  hydrated: false,
+  loading: false,
+
+  hydrate: async () => {
+    if (get().hydrated || get().loading) return;
+    // 1. Paint cached cards immediately (survives cold start / offline).
+    try {
+      const cached = await getAcsCacheStorage()?.getItem(CACHE_KEY);
+      if (cached) {
+        const parsed = JSON.parse(cached) as HomeAction[];
+        if (Array.isArray(parsed) && parsed.length > 0) {
+          // Preserve the order we cached (which was the server's priority
+          // order) — home layouts may split positionally, so re-sorting
+          // would reshuffle the hero cards.
+          set({ actions: parsed, hydrated: true });
+        }
+      }
+    } catch { /* corrupt cache — ignore, server refresh will fix it */ }
+    // 2. Then refresh from the server.
+    await get().refresh();
+  },
+
+  refresh: async () => {
+    if (get().loading) return;
+    set({ loading: true });
+    const actions = await listHomeActions();
+    // Only overwrite when the server actually returned cards. An empty result
+    // (dead API, transient 5xx, or genuinely-empty) must NOT wipe the cards
+    // already on screen — keep the last good set persisted.
+    if (actions.length > 0) {
+      // Server delivers cards already priority-ordered — do NOT re-sort
+      // (home layouts may be positional, e.g. a top-3 / rest split).
+      set({ actions, loading: false, hydrated: true });
+      persist(actions);
+    } else {
+      set({ loading: false, hydrated: true });
+    }
+  },
+
+  // clear() wipes in-memory state on sign-out AND drops the disk cache — a
+  // different user must not see the prior user's cards.
+  clear: () => {
+    set({ actions: [], hydrated: false, loading: false });
+    getAcsCacheStorage()?.setItem(CACHE_KEY, '[]').catch(() => {});
+  },
+
+  dismiss: async (actionId) => {
+    const before = get().actions;
+    const next = before.filter(a => a.actionId !== actionId);
+    set({ actions: next });
+    persist(next);
+    const r = await patchHomeAction(actionId, { dismissed: true }, 'user_dismiss');
+    if (r.ok) return { ok: true };
+    set({ actions: before });
+    persist(before);
+    return { ok: false, error: r.error || `HTTP ${r.status}` };
+  },
+
+  setPinned: async (actionId, pinned) => {
+    const before = get().actions;
+    const next = before.map(a => (a.actionId === actionId ? { ...a, pinned } : a)).sort(sortByPin);
+    set({ actions: next });
+    persist(next);
+    const r = await patchHomeAction(actionId, { pinned }, pinned ? 'user_pin' : 'user_unpin');
+    if (r.ok) {
+      if (r.action) {
+        const merged = get().actions.map(a => (a.actionId === actionId ? { ...a, ...r.action! } : a)).sort(sortByPin);
+        set({ actions: merged });
+        persist(merged);
+      }
+      return { ok: true };
+    }
+    set({ actions: before });
+    persist(before);
+    return { ok: false, error: r.error || `HTTP ${r.status}` };
+  },
+
+  reorder: async (orderedIds) => {
+    const before = get().actions;
+    const idx = new Map(orderedIds.map((id, i) => [id, i] as const));
+    const next = before.map(a => {
+      const o = idx.get(a.actionId);
+      return o == null ? a : { ...a, pinOrder: o };
+    }).sort(sortByPin);
+    set({ actions: next });
+    persist(next);
+    const r = await setHomeActionOrder(orderedIds);
+    if (r.ok) return { ok: true };
+    set({ actions: before });
+    persist(before);
+    return { ok: false, error: r.error || `HTTP ${r.status}` };
+  },
+
+  applyServerUpsert: (action) => {
+    const rest = get().actions.filter(a => a.actionId !== action.actionId);
+    const next = [...rest, action].sort(sortByPin);
+    set({ actions: next });
+    persist(next);
+  },
+  applyServerRemove: (actionId) => {
+    const next = get().actions.filter(a => a.actionId !== actionId);
+    set({ actions: next });
+    persist(next);
+  },
+  applyServerOrder: (orderedIds) => {
+    const idx = new Map(orderedIds.map((id, i) => [id, i] as const));
+    const next = get().actions.map(a => {
+      const o = idx.get(a.actionId);
+      return o == null ? a : { ...a, pinOrder: o };
+    }).sort(sortByPin);
+    set({ actions: next });
+    persist(next);
+  },
+}));

package/src/acs/providers.ts

@@ -0,0 +1,44 @@
+/**
+ * ACS host DI seams. Both optional — the ACS layer works without them:
+ * no reachability reporting, and the home-actions cache lives in memory only.
+ */
+
+/** Host hook fired on every ACS fetch outcome — a response (any status)
+ *  proves the server is reachable; a thrown fetch means it isn't. The
+ *  reference app wires this to its connectivity banner store. */
+export interface AcsReachabilityReporter {
+  up: () => void;
+  down: () => void;
+}
+
+let _reachability: AcsReachabilityReporter | null = null;
+
+export function setAcsReachabilityReporter(r: AcsReachabilityReporter | null): void {
+  _reachability = r;
+}
+
+export function reportAcsServerUp(): void {
+  try { _reachability?.up(); } catch {}
+}
+
+export function reportAcsServerDown(): void {
+  try { _reachability?.down(); } catch {}
+}
+
+/** Minimal async KV used to persist the home-actions feed across cold starts
+ *  (AsyncStorage-shaped). @ateam-ai-mobile/expo wires AsyncStorage in
+ *  setupExpoProviders(); without a provider the cache is a no-op. */
+export interface AcsKvStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+}
+
+let _kv: AcsKvStorage | null = null;
+
+export function setAcsCacheStorage(kv: AcsKvStorage | null): void {
+  _kv = kv;
+}
+
+export function getAcsCacheStorage(): AcsKvStorage | null {
+  return _kv;
+}