@agora-sdk/social-core 0.6.0

package/dist/cjs/hooks/useSocialNeighborhood.js

@@ -0,0 +1,90 @@
+"use strict";
+// useSocialNeighborhood — load the caller's own named ties (self-view), gated on the feature config.
+//
+// Self-gates on `config.neighborhoodEnabled`. Owns the `includeInteractions` toggle: it seeds from the
+// project default (`config.neighborhoodIncludeInteractions`) once config resolves, then re-fetches
+// whenever the caller flips it. The server always echoes the EFFECTIVE value, so we sync local state to
+// the response (`includesInteractions`) rather than trusting the request optimistically.
+//
+// Privacy (SOCIAL.md §6): the Neighborhood is self-view only and must not persist across sign-outs or
+// user switches. This hook keeps ties in component state only (no cache) and clears them when the lens
+// disables or the provider's client identity changes — so a project/token swap cannot leak a prior
+// user's ties.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSocialNeighborhood = useSocialNeighborhood;
+const react_1 = require("react");
+const rest_js_1 = require("../transport/rest.js");
+const social_context_js_1 = require("../context/social-context.js");
+/**
+ * Load the caller's Neighborhood — their own named ties with dyadic brightness. Self-view only.
+ *
+ * Waits for the provider's transparency config, seeds the `includeInteractions` toggle from the
+ * project default, then fetches `GET /social/neighborhood` only when `neighborhoodEnabled` is true.
+ * Flipping the toggle re-fetches; the hook syncs to the server's echoed effective value.
+ *
+ * @returns {@link UseSocialNeighborhoodValues} — the ties, load state, and the interactions toggle.
+ *
+ * @example
+ * ```tsx
+ * const { neighborhood, includeInteractions, setIncludeInteractions } = useSocialNeighborhood();
+ * ```
+ */
+function useSocialNeighborhood() {
+    const { rest, config, configLoading } = (0, social_context_js_1.useSocial)();
+    const enabled = config?.neighborhoodEnabled ?? false;
+    const projectDefault = config?.neighborhoodIncludeInteractions ?? false;
+    const [neighborhood, setNeighborhood] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [includeInteractions, setIncludeInteractions] = (0, react_1.useState)(false);
+    // Seed the toggle from the project default exactly once, when config first resolves. After that the
+    // caller owns it. A ref guards against re-seeding (which would clobber a user's choice on re-render).
+    const seeded = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        if (configLoading || seeded.current)
+            return;
+        setIncludeInteractions(projectDefault);
+        seeded.current = true;
+    }, [configLoading, projectDefault]);
+    const fetchFor = (0, react_1.useCallback)(async (include) => {
+        if (!enabled)
+            return;
+        setLoading(true);
+        setError(null);
+        try {
+            const result = await rest.getNeighborhood({ includeInteractions: include });
+            setNeighborhood(result);
+            // Sync to the server's effective value (it may override the request, e.g. project policy).
+            setIncludeInteractions(result.includesInteractions);
+        }
+        catch (err) {
+            // Fail soft on degradation (graph off, or the lens disabled mid-session): hide the surface —
+            // clear ties and swallow the error rather than surface it to members (SOCIAL.md §7). Real
+            // errors still propagate via `error`.
+            if ((0, rest_js_1.isSocialDegradation)(err)) {
+                setNeighborhood(null);
+                setError(null);
+            }
+            else {
+                setError(err);
+            }
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [enabled, rest]);
+    // Fetch on enable and whenever the toggle changes. Clear ties when disabled or before re-fetch under
+    // a new identity — the self-view must never linger across a user switch (SOCIAL.md §6).
+    (0, react_1.useEffect)(() => {
+        if (configLoading || !seeded.current)
+            return;
+        if (!enabled) {
+            setNeighborhood(null);
+            return;
+        }
+        void fetchFor(includeInteractions);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [configLoading, enabled, includeInteractions, fetchFor]);
+    return { neighborhood, loading, error, includeInteractions, setIncludeInteractions };
+}
+//# sourceMappingURL=useSocialNeighborhood.js.map

package/dist/cjs/hooks/useSocialNeighborhood.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSocialNeighborhood.js","sourceRoot":"","sources":["../../../src/hooks/useSocialNeighborhood.tsx"],"names":[],"mappings":"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"}

package/dist/cjs/hooks/useSocialTransparency.d.ts

@@ -0,0 +1,25 @@
+import { ResolvedSocialConfig } from "../contract/index.js";
+/** The state returned by {@link useSocialTransparency}. */
+export interface UseSocialTransparencyValues {
+    /** The resolved config, or `null` until the provider's transparency fetch resolves. */
+    config: ResolvedSocialConfig | null;
+    /** True while the provider's initial transparency fetch is in flight. */
+    loading: boolean;
+    /** A non-degradation error from the transparency fetch, or `null`. */
+    error: unknown;
+}
+/**
+ * Read the project's resolved social config (which lenses are enabled, decay half-lives, k-floor).
+ *
+ * Reads straight from the provider — no extra request. Returns `config: null` until the provider's
+ * mount-time transparency fetch resolves.
+ *
+ * @returns {@link UseSocialTransparencyValues} — the resolved config and its load state.
+ *
+ * @example
+ * ```tsx
+ * const { config } = useSocialTransparency();
+ * if (config?.weatherEnabled) renderWeatherNavEntry();
+ * ```
+ */
+export declare function useSocialTransparency(): UseSocialTransparencyValues;

package/dist/cjs/hooks/useSocialTransparency.js

@@ -0,0 +1,28 @@
+"use strict";
+// useSocialTransparency — read the project's resolved social config from the provider.
+//
+// The provider already fetches `GET /social/transparency` once on mount, so this hook issues no
+// request of its own — it just surfaces the cached config + load state. Use it to render a how-it-works
+// panel (which lenses are on, decay half-lives, k-floor) or to drive nav-entry visibility.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSocialTransparency = useSocialTransparency;
+const social_context_js_1 = require("../context/social-context.js");
+/**
+ * Read the project's resolved social config (which lenses are enabled, decay half-lives, k-floor).
+ *
+ * Reads straight from the provider — no extra request. Returns `config: null` until the provider's
+ * mount-time transparency fetch resolves.
+ *
+ * @returns {@link UseSocialTransparencyValues} — the resolved config and its load state.
+ *
+ * @example
+ * ```tsx
+ * const { config } = useSocialTransparency();
+ * if (config?.weatherEnabled) renderWeatherNavEntry();
+ * ```
+ */
+function useSocialTransparency() {
+    const { config, configLoading, configError } = (0, social_context_js_1.useSocial)();
+    return { config, loading: configLoading, error: configError };
+}
+//# sourceMappingURL=useSocialTransparency.js.map

package/dist/cjs/hooks/useSocialTransparency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSocialTransparency.js","sourceRoot":"","sources":["../../../src/hooks/useSocialTransparency.tsx"],"names":[],"mappings":";AAAA,uFAAuF;AACvF,EAAE;AACF,gGAAgG;AAChG,wGAAwG;AACxG,2FAA2F;;AA6B3F,sDAGC;AA7BD,oEAAyD;AAYzD;;;;;;;;;;;;;GAaG;AACH,SAAgB,qBAAqB;IACnC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,GAAG,IAAA,6BAAS,GAAE,CAAC;IAC3D,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;AAChE,CAAC"}

package/dist/cjs/hooks/useSocialWeather.d.ts

@@ -0,0 +1,28 @@
+import { SocialWeather } from "../contract/index.js";
+/** The state and actions returned by {@link useSocialWeather}. */
+export interface UseSocialWeatherValues {
+    /** The current Weather reading, or `null` while loading, when disabled, or on error. */
+    weather: SocialWeather | null;
+    /** True while a fetch is in flight (always `false` when the lens is disabled). */
+    loading: boolean;
+    /** The last error thrown by the fetch, or `null`. */
+    error: unknown;
+    /** Re-fetch the Weather reading. No-op when the lens is disabled. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Load the Community Weather scalar for the current project.
+ *
+ * Waits for the provider's transparency config, then fetches `GET /social/weather` only when
+ * `weatherEnabled` is true. When the lens is disabled it returns `{ weather: null, loading: false }`
+ * and issues no request.
+ *
+ * @returns {@link UseSocialWeatherValues} — the reading, load state, and a `refresh` action.
+ *
+ * @example
+ * ```tsx
+ * const { weather, loading } = useSocialWeather();
+ * if (!weather) return null; // disabled or still loading
+ * ```
+ */
+export declare function useSocialWeather(): UseSocialWeatherValues;

package/dist/cjs/hooks/useSocialWeather.js

@@ -0,0 +1,72 @@
+"use strict";
+// useSocialWeather — load the Community Weather scalar, gated on the project's feature config.
+//
+// Self-gates on `config.weatherEnabled` from the provider: when the lens is disabled (or the graph is
+// unavailable) the hook returns `weather: null` and never issues a request, so a host app can render
+// `<CommunityWeather />` unconditionally and have it disappear when off (SOCIAL.md §7). Weather is a
+// ~1h server-cached aggregate, so a single fetch on enable is enough; `refresh()` is exposed for
+// manual refetch (e.g. pull-to-refresh).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSocialWeather = useSocialWeather;
+const react_1 = require("react");
+const rest_js_1 = require("../transport/rest.js");
+const social_context_js_1 = require("../context/social-context.js");
+/**
+ * Load the Community Weather scalar for the current project.
+ *
+ * Waits for the provider's transparency config, then fetches `GET /social/weather` only when
+ * `weatherEnabled` is true. When the lens is disabled it returns `{ weather: null, loading: false }`
+ * and issues no request.
+ *
+ * @returns {@link UseSocialWeatherValues} — the reading, load state, and a `refresh` action.
+ *
+ * @example
+ * ```tsx
+ * const { weather, loading } = useSocialWeather();
+ * if (!weather) return null; // disabled or still loading
+ * ```
+ */
+function useSocialWeather() {
+    const { rest, config, configLoading } = (0, social_context_js_1.useSocial)();
+    const enabled = config?.weatherEnabled ?? false;
+    const [weather, setWeather] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const refresh = (0, react_1.useCallback)(async () => {
+        if (!enabled)
+            return;
+        setLoading(true);
+        setError(null);
+        try {
+            setWeather(await rest.getWeather());
+        }
+        catch (err) {
+            // Fail soft on degradation (graph off, or the lens disabled mid-session): hide the surface —
+            // clear the reading and swallow the error rather than surface it to members (SOCIAL.md §7). Real
+            // errors still propagate via `error`.
+            if ((0, rest_js_1.isSocialDegradation)(err)) {
+                setWeather(null);
+                setError(null);
+            }
+            else {
+                setError(err);
+            }
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [enabled, rest]);
+    // Fetch once the config has resolved and the lens is enabled. When disabled, clear any stale reading
+    // so a config flip to off (or a project switch) doesn't leave the previous community's weather on screen.
+    (0, react_1.useEffect)(() => {
+        if (configLoading)
+            return;
+        if (!enabled) {
+            setWeather(null);
+            return;
+        }
+        void refresh();
+    }, [configLoading, enabled, refresh]);
+    return { weather, loading, error, refresh };
+}
+//# sourceMappingURL=useSocialWeather.js.map

package/dist/cjs/hooks/useSocialWeather.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSocialWeather.js","sourceRoot":"","sources":["../../../src/hooks/useSocialWeather.tsx"],"names":[],"mappings":";AAAA,+FAA+F;AAC/F,EAAE;AACF,sGAAsG;AACtG,qGAAqG;AACrG,qGAAqG;AACrG,iGAAiG;AACjG,yCAAyC;;AAkCzC,4CAyCC;AAzED,iCAAyD;AAEzD,kDAA2D;AAC3D,oEAAyD;AAczD;;;;;;;;;;;;;;GAcG;AACH,SAAgB,gBAAgB;IAC9B,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,IAAA,6BAAS,GAAE,CAAC;IACpD,MAAM,OAAO,GAAG,MAAM,EAAE,cAAc,IAAI,KAAK,CAAC;IAEhD,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,IAAA,gBAAQ,EAAuB,IAAI,CAAC,CAAC;IACnE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,IAAA,gBAAQ,EAAC,KAAK,CAAC,CAAC;IAC9C,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,IAAA,gBAAQ,EAAU,IAAI,CAAC,CAAC;IAElD,MAAM,OAAO,GAAG,IAAA,mBAAW,EAAC,KAAK,IAAI,EAAE;QACrC,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,UAAU,CAAC,IAAI,CAAC,CAAC;QACjB,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,CAAC;YACH,UAAU,CAAC,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,6FAA6F;YAC7F,iGAAiG;YACjG,sCAAsC;YACtC,IAAI,IAAA,6BAAmB,EAAC,GAAG,CAAC,EAAE,CAAC;gBAC7B,UAAU,CAAC,IAAI,CAAC,CAAC;gBACjB,QAAQ,CAAC,IAAI,CAAC,CAAC;YACjB,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,GAAG,CAAC,CAAC;YAChB,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,UAAU,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;IACH,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IAEpB,qGAAqG;IACrG,0GAA0G;IAC1G,IAAA,iBAAS,EAAC,GAAG,EAAE;QACb,IAAI,aAAa;YAAE,OAAO;QAC1B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,UAAU,CAAC,IAAI,CAAC,CAAC;YACjB,OAAO;QACT,CAAC;QACD,KAAK,OAAO,EAAE,CAAC;IACjB,CAAC,EAAE,CAAC,aAAa,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IAEtC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC9C,CAAC"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,14 @@
+export { SocialProvider, useSocial, ALL_DISABLED_SOCIAL_CONFIG } from "./context/social-context.js";
+export type { SocialProviderProps, SocialContextValue } from "./context/social-context.js";
+export { useSocialWeather } from "./hooks/useSocialWeather.js";
+export type { UseSocialWeatherValues } from "./hooks/useSocialWeather.js";
+export { useSocialConstellation } from "./hooks/useSocialConstellation.js";
+export type { UseSocialConstellationValues } from "./hooks/useSocialConstellation.js";
+export { useSocialNeighborhood } from "./hooks/useSocialNeighborhood.js";
+export type { UseSocialNeighborhoodValues } from "./hooks/useSocialNeighborhood.js";
+export { useSocialTransparency } from "./hooks/useSocialTransparency.js";
+export type { UseSocialTransparencyValues } from "./hooks/useSocialTransparency.js";
+export { SocialRestClient, SocialApiError, isSocialDegradation } from "./transport/rest.js";
+export type { SocialRestConfig } from "./transport/rest.js";
+export { WEATHER_BANDS, BLOB_SIZE_BUCKETS, NEIGHBORHOOD_TIE_KINDS, } from "./contract/index.js";
+export type { SocialWeather, WeatherBand, SocialConstellation, ConstellationBlob, BlobSizeBucket, SocialNeighborhood, NeighborhoodTie, NeighborhoodTieKind, ResolvedSocialConfig, } from "./contract/index.js";

package/dist/cjs/index.js

@@ -0,0 +1,33 @@
+"use strict";
+// @agora-sdk/social-core — platform-agnostic client for the Agora social graph.
+//
+// Typed REST transport + provider/hooks for the three member-facing lenses (Weather, Constellation,
+// Neighborhood) plus the Transparency endpoint. Pure data — no crypto, no persistence, no realtime.
+// Platform packages (@agora-sdk/social-react-js, etc.) re-export this and add the visual components.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEIGHBORHOOD_TIE_KINDS = exports.BLOB_SIZE_BUCKETS = exports.WEATHER_BANDS = exports.isSocialDegradation = exports.SocialApiError = exports.SocialRestClient = exports.useSocialTransparency = exports.useSocialNeighborhood = exports.useSocialConstellation = exports.useSocialWeather = exports.ALL_DISABLED_SOCIAL_CONFIG = exports.useSocial = exports.SocialProvider = void 0;
+// ── context / provider ──────────────────────────────────────────────────────
+var social_context_js_1 = require("./context/social-context.js");
+Object.defineProperty(exports, "SocialProvider", { enumerable: true, get: function () { return social_context_js_1.SocialProvider; } });
+Object.defineProperty(exports, "useSocial", { enumerable: true, get: function () { return social_context_js_1.useSocial; } });
+Object.defineProperty(exports, "ALL_DISABLED_SOCIAL_CONFIG", { enumerable: true, get: function () { return social_context_js_1.ALL_DISABLED_SOCIAL_CONFIG; } });
+// ── hooks ────────────────────────────────────────────────────────────────────
+var useSocialWeather_js_1 = require("./hooks/useSocialWeather.js");
+Object.defineProperty(exports, "useSocialWeather", { enumerable: true, get: function () { return useSocialWeather_js_1.useSocialWeather; } });
+var useSocialConstellation_js_1 = require("./hooks/useSocialConstellation.js");
+Object.defineProperty(exports, "useSocialConstellation", { enumerable: true, get: function () { return useSocialConstellation_js_1.useSocialConstellation; } });
+var useSocialNeighborhood_js_1 = require("./hooks/useSocialNeighborhood.js");
+Object.defineProperty(exports, "useSocialNeighborhood", { enumerable: true, get: function () { return useSocialNeighborhood_js_1.useSocialNeighborhood; } });
+var useSocialTransparency_js_1 = require("./hooks/useSocialTransparency.js");
+Object.defineProperty(exports, "useSocialTransparency", { enumerable: true, get: function () { return useSocialTransparency_js_1.useSocialTransparency; } });
+// ── transport (for advanced / non-React use) ─────────────────────────────────
+var rest_js_1 = require("./transport/rest.js");
+Object.defineProperty(exports, "SocialRestClient", { enumerable: true, get: function () { return rest_js_1.SocialRestClient; } });
+Object.defineProperty(exports, "SocialApiError", { enumerable: true, get: function () { return rest_js_1.SocialApiError; } });
+Object.defineProperty(exports, "isSocialDegradation", { enumerable: true, get: function () { return rest_js_1.isSocialDegradation; } });
+// ── wire contract types + runtime const arrays (transitional — see ./contract) ──
+var index_js_1 = require("./contract/index.js");
+Object.defineProperty(exports, "WEATHER_BANDS", { enumerable: true, get: function () { return index_js_1.WEATHER_BANDS; } });
+Object.defineProperty(exports, "BLOB_SIZE_BUCKETS", { enumerable: true, get: function () { return index_js_1.BLOB_SIZE_BUCKETS; } });
+Object.defineProperty(exports, "NEIGHBORHOOD_TIE_KINDS", { enumerable: true, get: function () { return index_js_1.NEIGHBORHOOD_TIE_KINDS; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,EAAE;AACF,oGAAoG;AACpG,oGAAoG;AACpG,qGAAqG;;;AAErG,+EAA+E;AAC/E,iEAAoG;AAA3F,mHAAA,cAAc,OAAA;AAAE,8GAAA,SAAS,OAAA;AAAE,+HAAA,0BAA0B,OAAA;AAG9D,gFAAgF;AAChF,mEAA+D;AAAtD,uHAAA,gBAAgB,OAAA;AAEzB,+EAA2E;AAAlE,mIAAA,sBAAsB,OAAA;AAE/B,6EAAyE;AAAhE,iIAAA,qBAAqB,OAAA;AAE9B,6EAAyE;AAAhE,iIAAA,qBAAqB,OAAA;AAG9B,gFAAgF;AAChF,+CAA4F;AAAnF,2GAAA,gBAAgB,OAAA;AAAE,yGAAA,cAAc,OAAA;AAAE,8GAAA,mBAAmB,OAAA;AAG9D,mFAAmF;AACnF,gDAI6B;AAH3B,yGAAA,aAAa,OAAA;AACb,6GAAA,iBAAiB,OAAA;AACjB,kHAAA,sBAAsB,OAAA"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/transport/rest.d.ts

@@ -0,0 +1,105 @@
+import { ResolvedSocialConfig, SocialConstellation, SocialNeighborhood, SocialWeather } from "../contract/index.js";
+/**
+ * Configuration for {@link SocialRestClient}. The base URL and access token are read through resolver
+ * callbacks rather than captured once, so a late-set `baseUrl` or a refreshed token take effect on the
+ * next request without rebuilding the client.
+ */
+export interface SocialRestConfig {
+    /** Resolve the API base URL (e.g. `getApiBaseUrl()` from @agora-sdk/core → `http://host/v7`). */
+    getBaseUrl: () => string;
+    /** Resolve the current access token, or undefined when signed out. */
+    getAccessToken: () => string | undefined;
+    /** The Agora project id (path-scoped on every endpoint — a privacy boundary). */
+    projectId: string;
+}
+/**
+ * A failed social API call. Carries the HTTP `status` and, when the server supplied one, the machine
+ * `code` (e.g. `social/graph-unavailable`, `social/weather-disabled`) so callers can distinguish
+ * "hide this surface" degradation (SOCIAL.md §7) from an unexpected failure.
+ */
+export declare class SocialApiError extends Error {
+    /** HTTP status code, or `0` when the request never got a response (network error). */
+    readonly status: number;
+    /** The server's machine error code (e.g. `social/graph-unavailable`), or `null` if none was sent. */
+    readonly code: string | null;
+    /**
+     * @param message - Human-readable summary (never contains member PII).
+     * @param status - HTTP status code (`0` for a network-level failure).
+     * @param code - The server's machine error code, or `null`.
+     */
+    constructor(message: string, status: number, code: string | null);
+}
+/**
+ * Whether an error is a "hide this surface" degradation (graph unavailable or a feature-disabled lens)
+ * rather than a real failure. Hooks use this to fail soft — clearing data instead of surfacing the
+ * error to members (`docs/SOCIAL.md` §7).
+ *
+ * @param err - Any caught error.
+ * @returns `true` for a {@link SocialApiError} whose `code` is a known degradation code; else `false`.
+ */
+export declare function isSocialDegradation(err: unknown): boolean;
+/**
+ * Typed REST client for the Agora social graph.
+ *
+ * Wraps the four social endpoints in `docs/SOCIAL.md`. Each request lazily resolves the base URL and
+ * bearer token, scopes the path to `{baseUrl}/{projectId}/social`, and normalizes any failure into a
+ * {@link SocialApiError}.
+ *
+ * @remarks
+ * Construct this directly only for advanced / non-React use. Inside React, prefer the `SocialProvider`
+ * + hooks, which build and share one client for you.
+ *
+ * @example
+ * ```typescript
+ * const rest = new SocialRestClient({
+ *   projectId,
+ *   getBaseUrl: () => getApiBaseUrl(),
+ *   getAccessToken: () => session.accessToken,
+ * });
+ * const weather = await rest.getWeather();
+ * ```
+ */
+export declare class SocialRestClient {
+    private readonly config;
+    private readonly http;
+    /** @param config - Lazy resolvers for base URL + token, plus the path-scoped project id. */
+    constructor(config: SocialRestConfig);
+    /**
+     * Fetch the Community Weather scalar (aggregate warmth + band + 7-day trend).
+     *
+     * @returns The current {@link SocialWeather} reading (`value: null` / `band: "quiet"` when no data yet).
+     * @throws {SocialApiError} `400 social/weather-disabled` (feature off) or `503 social/graph-unavailable`.
+     */
+    getWeather(): Promise<SocialWeather>;
+    /**
+     * Fetch the Constellation snapshot (anonymous cluster blobs).
+     *
+     * @returns The current {@link SocialConstellation} (`asOf: null` when no snapshot exists yet).
+     * @throws {SocialApiError} `400 social/constellation-disabled` or `503 social/graph-unavailable`.
+     */
+    getConstellation(): Promise<SocialConstellation>;
+    /**
+     * Fetch the caller's Neighborhood (their own named ties with dyadic brightness). Self-view only.
+     *
+     * @param opts - Optional `includeInteractions` toggle; omit to use the project default. The response
+     *   always echoes the **effective** value via `includesInteractions`.
+     * @returns The caller's {@link SocialNeighborhood}, ties sorted brightest-first.
+     * @throws {SocialApiError} `400 social/neighborhood-disabled` or `503 social/graph-unavailable`.
+     */
+    getNeighborhood(opts?: {
+        includeInteractions?: boolean;
+    }): Promise<SocialNeighborhood>;
+    /**
+     * Fetch the project's resolved social config (which lenses are enabled, decay half-lives, k-floor).
+     * Call this at app init to know which surfaces to render.
+     *
+     * @returns The project's {@link ResolvedSocialConfig}.
+     * @throws {SocialApiError} `503 social/graph-unavailable` when the graph is not configured.
+     */
+    getTransparency(): Promise<ResolvedSocialConfig>;
+    /**
+     * Shared GET helper: issues the request and normalizes any axios failure into a {@link SocialApiError}
+     * carrying the HTTP status + server error code.
+     */
+    private get;
+}

package/dist/cjs/transport/rest.js

@@ -0,0 +1,177 @@
+"use strict";
+// Typed REST client for the Agora social graph (Weather / Constellation / Neighborhood / Transparency).
+//
+// Covers every endpoint in `docs/SOCIAL.md` §1–4. Base URL and access token are resolved **lazily per
+// request** (matching the @agora-sdk/core base-URL runtime), so a token refresh or a late-set baseUrl
+// always wins. Every endpoint is path-scoped to `{baseUrl}/{projectId}/social` — the `:projectId`
+// boundary is a privacy boundary (no cross-project social data; see SOCIAL.md §6).
+//
+// All four lenses are feature-gated server-side and degrade with specific error codes (SOCIAL.md §7).
+// On any non-2xx, this client throws a typed {@link SocialApiError} carrying the HTTP `status` plus the
+// server's machine `code` (e.g. `social/graph-unavailable`), so hooks/providers can hide a surface
+// rather than surface a raw error to members.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocialRestClient = exports.SocialApiError = void 0;
+exports.isSocialDegradation = isSocialDegradation;
+const axios_1 = __importDefault(require("axios"));
+/**
+ * A failed social API call. Carries the HTTP `status` and, when the server supplied one, the machine
+ * `code` (e.g. `social/graph-unavailable`, `social/weather-disabled`) so callers can distinguish
+ * "hide this surface" degradation (SOCIAL.md §7) from an unexpected failure.
+ */
+class SocialApiError extends Error {
+    /**
+     * @param message - Human-readable summary (never contains member PII).
+     * @param status - HTTP status code (`0` for a network-level failure).
+     * @param code - The server's machine error code, or `null`.
+     */
+    constructor(message, status, code) {
+        super(message);
+        this.name = "SocialApiError";
+        this.status = status;
+        this.code = code;
+    }
+}
+exports.SocialApiError = SocialApiError;
+/**
+ * Server error codes that mean "this surface is unavailable / turned off" rather than "something went
+ * wrong" — the graph being unconfigured (`503`) or a lens being feature-disabled (`400`). Per
+ * `docs/SOCIAL.md` §7 these should make the client **hide the surface**, never show a member an error.
+ */
+const SOCIAL_DEGRADATION_CODES = new Set([
+    "social/graph-unavailable",
+    "social/weather-disabled",
+    "social/constellation-disabled",
+    "social/neighborhood-disabled",
+]);
+/**
+ * Whether an error is a "hide this surface" degradation (graph unavailable or a feature-disabled lens)
+ * rather than a real failure. Hooks use this to fail soft — clearing data instead of surfacing the
+ * error to members (`docs/SOCIAL.md` §7).
+ *
+ * @param err - Any caught error.
+ * @returns `true` for a {@link SocialApiError} whose `code` is a known degradation code; else `false`.
+ */
+function isSocialDegradation(err) {
+    return (err instanceof SocialApiError && err.code !== null && SOCIAL_DEGRADATION_CODES.has(err.code));
+}
+/**
+ * Pull the server's machine error code out of an arbitrary error body. agora-server error shapes vary
+ * (`{ error: { code } }`, `{ code }`, or `{ error: "social/…" }`), so probe each defensively and fall
+ * back to `null`. Never throws.
+ */
+function extractCode(data) {
+    if (!data || typeof data !== "object")
+        return null;
+    const body = data;
+    const nested = body.error;
+    if (nested && typeof nested === "object" && typeof nested.code === "string") {
+        return nested.code;
+    }
+    if (typeof body.code === "string")
+        return body.code;
+    if (typeof nested === "string")
+        return nested;
+    return null;
+}
+/**
+ * Typed REST client for the Agora social graph.
+ *
+ * Wraps the four social endpoints in `docs/SOCIAL.md`. Each request lazily resolves the base URL and
+ * bearer token, scopes the path to `{baseUrl}/{projectId}/social`, and normalizes any failure into a
+ * {@link SocialApiError}.
+ *
+ * @remarks
+ * Construct this directly only for advanced / non-React use. Inside React, prefer the `SocialProvider`
+ * + hooks, which build and share one client for you.
+ *
+ * @example
+ * ```typescript
+ * const rest = new SocialRestClient({
+ *   projectId,
+ *   getBaseUrl: () => getApiBaseUrl(),
+ *   getAccessToken: () => session.accessToken,
+ * });
+ * const weather = await rest.getWeather();
+ * ```
+ */
+class SocialRestClient {
+    /** @param config - Lazy resolvers for base URL + token, plus the path-scoped project id. */
+    constructor(config) {
+        this.config = config;
+        this.http = axios_1.default.create();
+        this.http.interceptors.request.use((req) => {
+            const base = config.getBaseUrl().replace(/\/$/, "");
+            req.baseURL = `${base}/${config.projectId}/social`;
+            const token = config.getAccessToken();
+            if (token)
+                req.headers.set("Authorization", `Bearer ${token}`);
+            return req;
+        });
+    }
+    /**
+     * Fetch the Community Weather scalar (aggregate warmth + band + 7-day trend).
+     *
+     * @returns The current {@link SocialWeather} reading (`value: null` / `band: "quiet"` when no data yet).
+     * @throws {SocialApiError} `400 social/weather-disabled` (feature off) or `503 social/graph-unavailable`.
+     */
+    async getWeather() {
+        return this.get("/weather");
+    }
+    /**
+     * Fetch the Constellation snapshot (anonymous cluster blobs).
+     *
+     * @returns The current {@link SocialConstellation} (`asOf: null` when no snapshot exists yet).
+     * @throws {SocialApiError} `400 social/constellation-disabled` or `503 social/graph-unavailable`.
+     */
+    async getConstellation() {
+        return this.get("/constellation");
+    }
+    /**
+     * Fetch the caller's Neighborhood (their own named ties with dyadic brightness). Self-view only.
+     *
+     * @param opts - Optional `includeInteractions` toggle; omit to use the project default. The response
+     *   always echoes the **effective** value via `includesInteractions`.
+     * @returns The caller's {@link SocialNeighborhood}, ties sorted brightest-first.
+     * @throws {SocialApiError} `400 social/neighborhood-disabled` or `503 social/graph-unavailable`.
+     */
+    async getNeighborhood(opts) {
+        const params = opts?.includeInteractions === undefined
+            ? undefined
+            : { includeInteractions: opts.includeInteractions };
+        return this.get("/neighborhood", params);
+    }
+    /**
+     * Fetch the project's resolved social config (which lenses are enabled, decay half-lives, k-floor).
+     * Call this at app init to know which surfaces to render.
+     *
+     * @returns The project's {@link ResolvedSocialConfig}.
+     * @throws {SocialApiError} `503 social/graph-unavailable` when the graph is not configured.
+     */
+    async getTransparency() {
+        return this.get("/transparency");
+    }
+    /**
+     * Shared GET helper: issues the request and normalizes any axios failure into a {@link SocialApiError}
+     * carrying the HTTP status + server error code.
+     */
+    async get(path, params) {
+        try {
+            const { data } = await this.http.get(path, params ? { params } : undefined);
+            return data;
+        }
+        catch (err) {
+            if (axios_1.default.isAxiosError(err)) {
+                const status = err.response?.status ?? 0;
+                const code = extractCode(err.response?.data);
+                throw new SocialApiError(code ? `Social request failed: ${code}` : `Social request failed (HTTP ${status}).`, status, code);
+            }
+            throw err;
+        }
+    }
+}
+exports.SocialRestClient = SocialRestClient;
+//# sourceMappingURL=rest.js.map

package/dist/cjs/transport/rest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest.js","sourceRoot":"","sources":["../../../src/transport/rest.ts"],"names":[],"mappings":"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"}