@viyv/account-client 0.1.0

package/dist/introspect.cjs

@@ -0,0 +1,117 @@
+'use strict';
+
+// src/entitlement.ts
+function parseEntitlement(wire) {
+  return {
+    organizationId: wire.organization_id,
+    plan: wire.plan,
+    addons: wire.addons ?? [],
+    products: wire.products ?? [],
+    features: wire.features
+  };
+}
+
+// src/introspect.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+function createIntrospectionClient(config) {
+  const f = config.fetchImpl ?? fetch;
+  const base = config.apiBase.replace(/\/$/, "");
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const secretHeaders = {
+    "x-viyv-service-secret": config.serviceSecret
+  };
+  if (config.clientId) secretHeaders["x-viyv-client-id"] = config.clientId;
+  async function call(path, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      return await f(`${base}${path}`, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  return {
+    async introspectDevice(accessToken) {
+      let res;
+      try {
+        res = await call("/v1/auth/device/introspect", {
+          method: "POST",
+          headers: {
+            ...secretHeaders,
+            authorization: `Bearer ${accessToken}`,
+            "content-type": "application/json"
+          },
+          body: "{}"
+        });
+      } catch (err) {
+        return { status: "unavailable", reason: `introspect transport error: ${errMessage(err)}` };
+      }
+      if (res.status === 401) {
+        return {
+          status: "unavailable",
+          reason: "introspect unauthorized (service secret / server config)"
+        };
+      }
+      if (!res.ok) {
+        return { status: "unavailable", reason: `introspect http ${res.status}` };
+      }
+      let raw;
+      try {
+        raw = await res.json();
+      } catch (err) {
+        return { status: "integrity_error", reason: `introspect unparseable body: ${errMessage(err)}` };
+      }
+      if (!raw || typeof raw !== "object") {
+        return { status: "integrity_error", reason: "introspect non-object body" };
+      }
+      const body = raw;
+      if (body.active !== true) {
+        return { status: "inactive" };
+      }
+      if (!body.org_id || !body.user_id) {
+        return { status: "integrity_error", reason: "active token missing org_id/user_id" };
+      }
+      return {
+        status: "active",
+        subject: {
+          orgId: body.org_id,
+          userId: body.user_id,
+          deviceId: body.device_id ?? null,
+          scope: body.scope,
+          expiresAtUnix: body.exp,
+          clientId: body.client_id ?? null,
+          email: body.email ?? null,
+          name: body.name ?? null,
+          orgName: body.org_name ?? null
+        }
+      };
+    },
+    async getOrgEntitlement(orgId) {
+      let res;
+      try {
+        res = await call(`/v1/license/entitlement/by-org?org_id=${encodeURIComponent(orgId)}`, {
+          method: "GET",
+          headers: secretHeaders
+        });
+      } catch (err) {
+        return { status: "unavailable", reason: `entitlement transport error: ${errMessage(err)}` };
+      }
+      if (!res.ok) {
+        return { status: "unavailable", reason: `entitlement http ${res.status}` };
+      }
+      try {
+        const wire = await res.json();
+        return { status: "ok", entitlement: parseEntitlement(wire) };
+      } catch (err) {
+        return { status: "unavailable", reason: `entitlement unparseable body: ${errMessage(err)}` };
+      }
+    }
+  };
+}
+function errMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+exports.createIntrospectionClient = createIntrospectionClient;
+//# sourceMappingURL=introspect.cjs.map
+//# sourceMappingURL=introspect.cjs.map

package/dist/introspect.d.cts

@@ -0,0 +1,67 @@
+import { E as Entitlement } from './entitlement-B3pXM2vO.cjs';
+import '@viyv/shared';
+
+interface IntrospectionClientConfig {
+    /** e.g. "https://api.viyv.io". */
+    apiBase: string;
+    /**
+     * Shared m2m secret (== viyv-account `INTERNAL_SERVICE_SECRET`). CALLER-INJECTED
+     * on purpose: this lib never reads it from the environment, so it can never
+     * bundle or log the secret. Pass it from your own server config.
+     */
+    serviceSecret: string;
+    /** Optional caller id, sent as `x-viyv-client-id` for the server's audit log. */
+    clientId?: string;
+    /** Injectable fetch (Node). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Per-request timeout (ms). Default 5000. A timeout maps to `unavailable`. */
+    timeoutMs?: number;
+}
+/** Subject resolved from an ACTIVE device access token (camelCase). */
+interface ResolvedDeviceSubject {
+    orgId: string;
+    userId: string;
+    deviceId: string | null;
+    scope: string;
+    /** Access-token expiry, seconds since the Unix epoch. */
+    expiresAtUnix: number;
+    clientId: string | null;
+    email: string | null;
+    name: string | null;
+    orgName: string | null;
+}
+/**
+ * Discriminated outcome of introspecting a device access token. Consumers MUST
+ * branch on every case — that is the point: the type system forces handling of
+ * the tamper (`integrity_error`) and `unavailable` cases that hand-rolled
+ * clients have historically conflated with `inactive`.
+ */
+type IntrospectionOutcome = {
+    status: "active";
+    subject: ResolvedDeviceSubject;
+} | {
+    status: "inactive";
+} | {
+    status: "unavailable";
+    reason: string;
+} | {
+    status: "integrity_error";
+    reason: string;
+};
+/** Outcome of an m2m org-entitlement read. */
+type OrgEntitlementOutcome = {
+    status: "ok";
+    entitlement: Entitlement;
+} | {
+    status: "unavailable";
+    reason: string;
+};
+interface IntrospectionClient {
+    /** Resolve a device access token to a subject (fail-closed, see taxonomy). */
+    introspectDevice(accessToken: string): Promise<IntrospectionOutcome>;
+    /** Read an org's entitlement by id (m2m). */
+    getOrgEntitlement(orgId: string): Promise<OrgEntitlementOutcome>;
+}
+declare function createIntrospectionClient(config: IntrospectionClientConfig): IntrospectionClient;
+
+export { type IntrospectionClient, type IntrospectionClientConfig, type IntrospectionOutcome, type OrgEntitlementOutcome, type ResolvedDeviceSubject, createIntrospectionClient };

package/dist/introspect.d.ts

@@ -0,0 +1,67 @@
+import { E as Entitlement } from './entitlement-B3pXM2vO.js';
+import '@viyv/shared';
+
+interface IntrospectionClientConfig {
+    /** e.g. "https://api.viyv.io". */
+    apiBase: string;
+    /**
+     * Shared m2m secret (== viyv-account `INTERNAL_SERVICE_SECRET`). CALLER-INJECTED
+     * on purpose: this lib never reads it from the environment, so it can never
+     * bundle or log the secret. Pass it from your own server config.
+     */
+    serviceSecret: string;
+    /** Optional caller id, sent as `x-viyv-client-id` for the server's audit log. */
+    clientId?: string;
+    /** Injectable fetch (Node). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Per-request timeout (ms). Default 5000. A timeout maps to `unavailable`. */
+    timeoutMs?: number;
+}
+/** Subject resolved from an ACTIVE device access token (camelCase). */
+interface ResolvedDeviceSubject {
+    orgId: string;
+    userId: string;
+    deviceId: string | null;
+    scope: string;
+    /** Access-token expiry, seconds since the Unix epoch. */
+    expiresAtUnix: number;
+    clientId: string | null;
+    email: string | null;
+    name: string | null;
+    orgName: string | null;
+}
+/**
+ * Discriminated outcome of introspecting a device access token. Consumers MUST
+ * branch on every case — that is the point: the type system forces handling of
+ * the tamper (`integrity_error`) and `unavailable` cases that hand-rolled
+ * clients have historically conflated with `inactive`.
+ */
+type IntrospectionOutcome = {
+    status: "active";
+    subject: ResolvedDeviceSubject;
+} | {
+    status: "inactive";
+} | {
+    status: "unavailable";
+    reason: string;
+} | {
+    status: "integrity_error";
+    reason: string;
+};
+/** Outcome of an m2m org-entitlement read. */
+type OrgEntitlementOutcome = {
+    status: "ok";
+    entitlement: Entitlement;
+} | {
+    status: "unavailable";
+    reason: string;
+};
+interface IntrospectionClient {
+    /** Resolve a device access token to a subject (fail-closed, see taxonomy). */
+    introspectDevice(accessToken: string): Promise<IntrospectionOutcome>;
+    /** Read an org's entitlement by id (m2m). */
+    getOrgEntitlement(orgId: string): Promise<OrgEntitlementOutcome>;
+}
+declare function createIntrospectionClient(config: IntrospectionClientConfig): IntrospectionClient;
+
+export { type IntrospectionClient, type IntrospectionClientConfig, type IntrospectionOutcome, type OrgEntitlementOutcome, type ResolvedDeviceSubject, createIntrospectionClient };

package/dist/introspect.js

@@ -0,0 +1,106 @@
+import { parseEntitlement } from './chunk-UX6UAFIF.js';
+
+// src/introspect.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+function createIntrospectionClient(config) {
+  const f = config.fetchImpl ?? fetch;
+  const base = config.apiBase.replace(/\/$/, "");
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const secretHeaders = {
+    "x-viyv-service-secret": config.serviceSecret
+  };
+  if (config.clientId) secretHeaders["x-viyv-client-id"] = config.clientId;
+  async function call(path, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      return await f(`${base}${path}`, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  return {
+    async introspectDevice(accessToken) {
+      let res;
+      try {
+        res = await call("/v1/auth/device/introspect", {
+          method: "POST",
+          headers: {
+            ...secretHeaders,
+            authorization: `Bearer ${accessToken}`,
+            "content-type": "application/json"
+          },
+          body: "{}"
+        });
+      } catch (err) {
+        return { status: "unavailable", reason: `introspect transport error: ${errMessage(err)}` };
+      }
+      if (res.status === 401) {
+        return {
+          status: "unavailable",
+          reason: "introspect unauthorized (service secret / server config)"
+        };
+      }
+      if (!res.ok) {
+        return { status: "unavailable", reason: `introspect http ${res.status}` };
+      }
+      let raw;
+      try {
+        raw = await res.json();
+      } catch (err) {
+        return { status: "integrity_error", reason: `introspect unparseable body: ${errMessage(err)}` };
+      }
+      if (!raw || typeof raw !== "object") {
+        return { status: "integrity_error", reason: "introspect non-object body" };
+      }
+      const body = raw;
+      if (body.active !== true) {
+        return { status: "inactive" };
+      }
+      if (!body.org_id || !body.user_id) {
+        return { status: "integrity_error", reason: "active token missing org_id/user_id" };
+      }
+      return {
+        status: "active",
+        subject: {
+          orgId: body.org_id,
+          userId: body.user_id,
+          deviceId: body.device_id ?? null,
+          scope: body.scope,
+          expiresAtUnix: body.exp,
+          clientId: body.client_id ?? null,
+          email: body.email ?? null,
+          name: body.name ?? null,
+          orgName: body.org_name ?? null
+        }
+      };
+    },
+    async getOrgEntitlement(orgId) {
+      let res;
+      try {
+        res = await call(`/v1/license/entitlement/by-org?org_id=${encodeURIComponent(orgId)}`, {
+          method: "GET",
+          headers: secretHeaders
+        });
+      } catch (err) {
+        return { status: "unavailable", reason: `entitlement transport error: ${errMessage(err)}` };
+      }
+      if (!res.ok) {
+        return { status: "unavailable", reason: `entitlement http ${res.status}` };
+      }
+      try {
+        const wire = await res.json();
+        return { status: "ok", entitlement: parseEntitlement(wire) };
+      } catch (err) {
+        return { status: "unavailable", reason: `entitlement unparseable body: ${errMessage(err)}` };
+      }
+    }
+  };
+}
+function errMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export { createIntrospectionClient };
+//# sourceMappingURL=introspect.js.map
+//# sourceMappingURL=introspect.js.map

package/dist/react.cjs

@@ -0,0 +1,214 @@
+'use strict';
+
+var react = require('react');
+var client = require('better-auth/client');
+
+// src/entitlement.ts
+function parseEntitlement(wire) {
+  return {
+    organizationId: wire.organization_id,
+    plan: wire.plan,
+    addons: wire.addons ?? [],
+    products: wire.products ?? [],
+    features: wire.features
+  };
+}
+function entitlementForProduct(entitlement, product) {
+  if (!entitlement) return null;
+  return {
+    enabled: entitlement.products.includes(product),
+    plan: entitlement.plan,
+    addons: entitlement.addons,
+    features: entitlement.features
+  };
+}
+function createAccountClient(config) {
+  const client$1 = client.createAuthClient({
+    baseURL: config.apiBase,
+    basePath: "/v1/auth",
+    fetchOptions: { credentials: "include" }
+  });
+  return {
+    raw: client$1,
+    signUp: (params) => client$1.signUp.email({
+      email: params.email,
+      password: params.password,
+      name: params.name ?? params.email.split("@")[0] ?? params.email
+    }),
+    signIn: (params) => client$1.signIn.email({
+      email: params.email,
+      password: params.password
+    }),
+    signOut: () => client$1.signOut(),
+    getSession: () => client$1.getSession()
+  };
+}
+
+// src/provider.tsx
+async function fetchJson(doFetch, url, signal) {
+  const res = await doFetch(url, { credentials: "include", signal });
+  if (res.status === 401 || res.status === 404) return null;
+  if (!res.ok) throw new Error(`${url} \u2192 ${res.status}`);
+  const text = await res.text();
+  if (!text || text === "null") return null;
+  return JSON.parse(text);
+}
+var SIGNED_OUT = {
+  status: "unauthenticated",
+  user: null,
+  activeOrg: null,
+  entitlement: null
+};
+async function loadAccount(apiBase, opts = {}) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const session = await fetchJson(
+    doFetch,
+    `${apiBase}/v1/auth/get-session`,
+    opts.signal
+  );
+  if (!session?.user) return SIGNED_OUT;
+  const user = {
+    id: session.user.id,
+    email: session.user.email,
+    name: session.user.name ?? null,
+    image: session.user.image ?? null
+  };
+  const [ent, orgsBody] = await Promise.all([
+    opts.skipEntitlement ? Promise.resolve(null) : fetchJson(
+      doFetch,
+      `${apiBase}/v1/license/entitlement`,
+      opts.signal
+    ),
+    fetchJson(doFetch, `${apiBase}/v1/users/me/orgs`, opts.signal)
+  ]);
+  const entitlement = ent ? parseEntitlement(ent) : null;
+  const activeId = session.session?.activeOrganizationId ?? entitlement?.organizationId ?? null;
+  const orgs = orgsBody?.organizations ?? [];
+  const match = activeId ? orgs.find((o) => o.organization_id === activeId) : orgs[0];
+  const activeOrg = match ? { id: match.organization_id, slug: match.slug ?? null, name: match.name ?? null } : activeId ? { id: activeId, slug: null, name: null } : null;
+  return { status: "authenticated", user, activeOrg, entitlement };
+}
+var AccountContext = react.createContext(null);
+function AccountProvider({
+  apiBase,
+  cookieDomain,
+  signInUrl = "https://app.viyv.io/signin",
+  skipEntitlement = false,
+  children
+}) {
+  const clientRef = react.useRef(null);
+  if (!clientRef.current) {
+    clientRef.current = createAccountClient({ apiBase});
+  }
+  const [status, setStatus] = react.useState("loading");
+  const [user, setUser] = react.useState(null);
+  const [activeOrg, setActiveOrg] = react.useState(null);
+  const [entitlement, setEntitlement] = react.useState(null);
+  const [error, setError] = react.useState(null);
+  const load = react.useCallback(
+    async (signal) => {
+      try {
+        setError(null);
+        const result = await loadAccount(apiBase, { skipEntitlement, signal });
+        setUser(result.user);
+        setActiveOrg(result.activeOrg);
+        setEntitlement(result.entitlement);
+        setStatus(result.status);
+      } catch (err) {
+        if (signal?.aborted) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setUser(null);
+        setActiveOrg(null);
+        setEntitlement(null);
+        setStatus("unauthenticated");
+      }
+    },
+    [apiBase, skipEntitlement]
+  );
+  react.useEffect(() => {
+    const ctrl = new AbortController();
+    void load(ctrl.signal);
+    return () => ctrl.abort();
+  }, [load]);
+  const signIn = react.useCallback(
+    (returnTo) => {
+      if (typeof window === "undefined") return;
+      const back = returnTo ?? window.location.href;
+      window.location.assign(`${signInUrl}?return_to=${encodeURIComponent(back)}`);
+    },
+    [signInUrl]
+  );
+  const signOut = react.useCallback(async () => {
+    await clientRef.current?.signOut();
+    setUser(null);
+    setActiveOrg(null);
+    setEntitlement(null);
+    setStatus("unauthenticated");
+  }, []);
+  const value = react.useMemo(
+    () => ({
+      status,
+      user,
+      activeOrg,
+      entitlement,
+      error,
+      refresh: () => load(),
+      signIn,
+      signOut,
+      apiBase,
+      signInUrl
+    }),
+    [status, user, activeOrg, entitlement, error, load, signIn, signOut, apiBase, signInUrl]
+  );
+  return react.createElement(AccountContext.Provider, { value }, children);
+}
+function useAccount() {
+  const ctx = react.useContext(AccountContext);
+  if (!ctx) throw new Error("useAccount must be used within <AccountProvider>");
+  return ctx;
+}
+function useUser() {
+  return useAccount().user;
+}
+function useActiveOrg() {
+  return useAccount().activeOrg;
+}
+function useEntitlement(product) {
+  const { entitlement } = useAccount();
+  return react.useMemo(() => entitlementForProduct(entitlement, product), [entitlement, product]);
+}
+
+// src/components.tsx
+function SignInButton({ returnTo, children, className }) {
+  const { signIn } = useAccount();
+  return react.createElement(
+    "button",
+    { type: "button", className, onClick: () => signIn(returnTo) },
+    children ?? "Sign in"
+  );
+}
+function SignOutButton({ children, className, onSignedOut }) {
+  const { signOut } = useAccount();
+  return react.createElement(
+    "button",
+    {
+      type: "button",
+      className,
+      onClick: async () => {
+        await signOut();
+        onSignedOut?.();
+      }
+    },
+    children ?? "Sign out"
+  );
+}
+
+exports.AccountProvider = AccountProvider;
+exports.SignInButton = SignInButton;
+exports.SignOutButton = SignOutButton;
+exports.useAccount = useAccount;
+exports.useActiveOrg = useActiveOrg;
+exports.useEntitlement = useEntitlement;
+exports.useUser = useUser;
+//# sourceMappingURL=react.cjs.map
+//# sourceMappingURL=react.cjs.map

package/dist/react.d.cts

@@ -0,0 +1,102 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { PlanTier, ProductSlug, EntitlementFeatures } from '@viyv/shared';
+export { EntitlementFeatures, PlanTier, ProductSlug } from '@viyv/shared';
+
+interface SignInButtonProps {
+    /** Where to return after sign-in. Default: current URL. */
+    returnTo?: string;
+    children?: ReactNode;
+    className?: string;
+}
+/** Redirects to the hosted sign-in page (app.viyv.io) with a return_to. */
+declare function SignInButton({ returnTo, children, className }: SignInButtonProps): react.DetailedReactHTMLElement<{
+    type: string;
+    className: string | undefined;
+    onClick: () => void;
+}, HTMLElement>;
+interface SignOutButtonProps {
+    children?: ReactNode;
+    className?: string;
+    onSignedOut?: () => void;
+}
+/** Signs out via better-auth and clears local account state. */
+declare function SignOutButton({ children, className, onSignedOut }: SignOutButtonProps): react.DetailedReactHTMLElement<{
+    type: string;
+    className: string | undefined;
+    onClick: () => Promise<void>;
+}, HTMLElement>;
+
+/** The signed-in user as returned by better-auth's get-session. */
+interface AccountUser {
+    id: string;
+    email: string;
+    name?: string | null;
+    image?: string | null;
+}
+/** Active organization, when the session carries one. */
+interface AccountOrg {
+    id: string;
+    slug?: string | null;
+    name?: string | null;
+}
+/** Shape of GET /v1/license/entitlement (docs/09 A-4). */
+interface Entitlement {
+    organizationId: string;
+    plan: PlanTier;
+    addons: string[];
+    /** Product slugs this org may use (free-start lists the agent family). */
+    products: ProductSlug[];
+    features: EntitlementFeatures;
+}
+/** Per-product entitlement view returned by useEntitlement(slug). */
+interface ProductEntitlement {
+    /** Whether the product is enabled for this org. */
+    enabled: boolean;
+    plan: PlanTier;
+    addons: string[];
+    /** The full feature map (callers branch on the flags they care about). */
+    features: EntitlementFeatures;
+}
+
+type AccountStatus = "loading" | "authenticated" | "unauthenticated";
+interface AccountContextValue {
+    status: AccountStatus;
+    user: AccountUser | null;
+    activeOrg: AccountOrg | null;
+    entitlement: Entitlement | null;
+    error: Error | null;
+    /** Re-fetch session + entitlement (e.g. after returning from checkout). */
+    refresh: () => Promise<void>;
+    /** Redirect to the hosted sign-in page (app.viyv.io) with a return_to. */
+    signIn: (returnTo?: string) => void;
+    /** Sign out via better-auth and drop local state. */
+    signOut: () => Promise<void>;
+    apiBase: string;
+    signInUrl: string;
+}
+interface AccountProviderProps {
+    /** e.g. "https://api.viyv.io" */
+    apiBase: string;
+    /** e.g. ".viyv.io" — kept for parity with docs/04 (cookies are server-set). */
+    cookieDomain?: string;
+    /** Hosted sign-in page. Default "https://app.viyv.io/signin". */
+    signInUrl?: string;
+    /** Skip the entitlement fetch (session-only consumers). Default false. */
+    skipEntitlement?: boolean;
+    children?: ReactNode;
+}
+declare function AccountProvider({ apiBase, cookieDomain, signInUrl, skipEntitlement, children, }: AccountProviderProps): react.FunctionComponentElement<react.ProviderProps<AccountContextValue | null>>;
+/** Read the full account context. Throws if used outside <AccountProvider>. */
+declare function useAccount(): AccountContextValue;
+/** The signed-in user, or null when unauthenticated/loading. */
+declare function useUser(): AccountUser | null;
+/** The active organization, or null. */
+declare function useActiveOrg(): AccountOrg | null;
+/**
+ * Per-product entitlement view. Returns null while loading / unauthenticated.
+ * Web products gate features on the returned `enabled` + `features` flags.
+ */
+declare function useEntitlement(product: ProductSlug): ProductEntitlement | null;
+
+export { type AccountContextValue, type AccountOrg, AccountProvider, type AccountProviderProps, type AccountStatus, type AccountUser, type Entitlement, type ProductEntitlement, SignInButton, type SignInButtonProps, SignOutButton, type SignOutButtonProps, useAccount, useActiveOrg, useEntitlement, useUser };