@fractalshq/sync 0.0.11 → 0.1.1

package/README.md

@@ -1,24 +1,66 @@
 # @fractalshq/sync
 
-Fractals Sync is the all-in-one SDK for the distribution platform. It ships as a single package with subpath exports so integrators can pick only what they need:
+Fractals Sync is the all-in-one SDK for the distribution platform. The default `@fractalshq/sync` export points to v2, and v1 is still available via explicit subpaths.
 
 ```
-@fractalshq/sync/core     // shared types + helpers (pure TS)
-@fractalshq/sync/server   // Node/Next client that talks to /api/v1
-@fractalshq/sync/react    // hooks that assume AuthProvider + wallet context
-@fractalshq/sync/widgets  // drop-in UI with its own provider stack
+@fractalshq/sync          // default v2 surface (claims + tx build only)
+@fractalshq/sync/v2       // public v2 surface (claims + tx build only)
+@fractalshq/sync/v2/core  // v2 core helpers (build tx + list claims)
+@fractalshq/sync/v2/react // v2 React hooks (useClaims, useClaimTransaction)
+@fractalshq/sync/v1/core     // shared types + helpers (pure TS)
+@fractalshq/sync/v1/server   // Node/Next client that talks to /api/v1
+@fractalshq/sync/v1/react    // hooks that assume AuthProvider + wallet context
+@fractalshq/sync/v1/widgets  // drop-in UI with its own provider stack
 ```
 
+Legacy v1 aliases (mapped to v1): `@fractalshq/sync/core`, `@fractalshq/sync/server`, `@fractalshq/sync/react`, `@fractalshq/sync/widgets`.
+
 ## Layout
 
 ```
 packages/sync/
 ├── src/
-│   ├── core/      // typed constants, schemas, memo builders
-│   ├── server/    // moved from @fractalshq/distribution-server
-│   ├── react/     // hooks + helpers (will absorb old distribution-client work)
-│   └── widgets/   // claim panels, buttons, etc.
+│   ├── v1/
+│   │   ├── core/      // typed constants, schemas, memo builders
+│   │   ├── server/    // moved from @fractalshq/distribution-server
+│   │   ├── react/     // hooks + helpers (will absorb old distribution-client work)
+│   │   └── widgets/   // claim panels, buttons, etc.
+│   └── v2/            // public v2 API surface (claims + tx build)
 └── package.json   // exports map for subpaths
 ```
 
+## V2 (public claims surface)
+
+V2 is intentionally tiny and public-facing. It only exposes:
+
+- `GET /api/v2/claims?wallet=<pubkey>` (claimable + claimed)
+- `POST /api/v2/claims/[id]/create-transaction` (build claim tx)
+
+### Core usage
+
+```ts
+import { listClaims, buildClaimTransaction } from "@fractalshq/sync/v2/core";
+
+const claims = await listClaims(wallet);
+const tx = await buildClaimTransaction({
+  distributionId,
+  claimant: wallet,
+});
+```
+
+### React usage
+
+```tsx
+import { useClaims, useClaimTransaction } from "@fractalshq/sync/v2/react";
+
+const claimsQuery = useClaims(wallet);
+const buildTx = useClaimTransaction();
+buildTx.mutateAsync({ distributionId, claimant: wallet });
+```
+
+Notes:
+- Default base path is `/api/v2` (override via `NEXT_PUBLIC_SYNC_V2_PATH`).
+- V2 requests are `credentials: "omit"` for public CORS mode.
+- If `wallet` is omitted, `useClaims` falls back to the Solana wallet adapter context (`@solana/wallet-adapter-react`).
+
 See `docs/distro-sdk.md` and `docs/distribution-sdk-auth-facts.md` for the full design notes / TODOs.

package/dist/chunk-4ZYNBLY5.mjs

@@ -0,0 +1,129 @@
+import {
+  __objRest,
+  __spreadValues
+} from "./chunk-FWCSY2DS.mjs";
+
+// src/v2/core/http.ts
+var FALLBACK_BASE_PATH = "/api/v2";
+var _a, _b;
+var ENV_BASE_PATH = typeof process !== "undefined" && (((_a = process.env) == null ? void 0 : _a.NEXT_PUBLIC_SYNC_V2_PATH) || ((_b = process.env) == null ? void 0 : _b.NEXT_PUBLIC_FRACTALS_SYNC_V2_PATH)) || void 0;
+var DEFAULT_BASE_PATH = sanitizeBasePath(ENV_BASE_PATH || FALLBACK_BASE_PATH);
+function resolveRequestConfig(options) {
+  return {
+    basePath: sanitizeBasePath((options == null ? void 0 : options.basePath) || DEFAULT_BASE_PATH),
+    fetcher: resolveFetcher(options == null ? void 0 : options.fetcher)
+  };
+}
+var SyncReactError = class extends Error {
+  constructor(status, code, details) {
+    super(code || `Sync request failed with status ${status}`);
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.name = "SyncReactError";
+  }
+};
+async function requestJSON(config, path, init) {
+  var _a2;
+  const url = buildUrl(config.basePath, path);
+  const requestInit = prepareInit(init);
+  requestInit.credentials = (_a2 = requestInit.credentials) != null ? _a2 : "omit";
+  const response = await config.fetcher(url, requestInit);
+  const payload = await parseResponseBody(response);
+  if (!response.ok) {
+    const errorCode = typeof payload === "object" && payload && "error" in payload ? String(payload.error) : void 0;
+    throw new SyncReactError(response.status, errorCode, payload);
+  }
+  return payload;
+}
+function resolveFetcher(custom) {
+  if (custom) return custom;
+  if (typeof fetch === "function") return fetch.bind(globalThis);
+  throw new Error("Global fetch is not available. Provide a fetcher via Sync configuration.");
+}
+function sanitizeBasePath(path) {
+  if (!path) return FALLBACK_BASE_PATH;
+  const trimmed = path.trim();
+  if (!trimmed || trimmed === "/") return "/";
+  return trimmed.replace(/\/+$/, "");
+}
+function buildUrl(basePath, path) {
+  if (path && isAbsoluteUrl(path)) return path;
+  const normalizedBase = sanitizeBasePath(basePath);
+  const suffix = path ? `/${path.replace(/^\/+/, "")}` : "";
+  if (!normalizedBase || normalizedBase === "/") {
+    return suffix ? suffix : normalizedBase;
+  }
+  return `${normalizedBase}${suffix}`;
+}
+function isAbsoluteUrl(path) {
+  return /^https?:\/\//i.test(path);
+}
+function isRelativeUrl(path) {
+  return !isAbsoluteUrl(path);
+}
+function prepareInit(init) {
+  const finalInit = __spreadValues({}, init);
+  if ((init == null ? void 0 : init.headers) instanceof Headers) {
+    const cloned = new Headers(init.headers);
+    if (!cloned.has("content-type")) cloned.set("content-type", "application/json");
+    finalInit.headers = cloned;
+    return finalInit;
+  }
+  const headers = new Headers(init == null ? void 0 : init.headers);
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  finalInit.headers = headers;
+  return finalInit;
+}
+async function parseResponseBody(response) {
+  if (response.status === 204) return void 0;
+  const text = await response.text();
+  if (!text) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    return text;
+  }
+}
+
+// src/v2/core/api.ts
+async function buildClaimTransaction(input, options) {
+  const distributionId = input == null ? void 0 : input.distributionId;
+  if (!distributionId) {
+    throw new SyncReactError(400, "distribution_id_required");
+  }
+  const config = resolveRequestConfig(options);
+  const _a2 = input, { distributionId: _unused } = _a2, body = __objRest(_a2, ["distributionId"]);
+  return requestJSON(
+    config,
+    `/claims/${encodeURIComponent(distributionId)}/create-transaction`,
+    {
+      method: "POST",
+      body: JSON.stringify(body)
+    }
+  );
+}
+async function listClaims(wallet, options) {
+  if (!wallet) {
+    throw new SyncReactError(400, "wallet_required");
+  }
+  const config = resolveRequestConfig(options);
+  const qs = new URLSearchParams({ wallet }).toString();
+  return requestJSON(config, `/claims?${qs}`, { method: "GET" });
+}
+
+export {
+  DEFAULT_BASE_PATH,
+  resolveRequestConfig,
+  SyncReactError,
+  requestJSON,
+  resolveFetcher,
+  sanitizeBasePath,
+  buildUrl,
+  isAbsoluteUrl,
+  isRelativeUrl,
+  buildClaimTransaction,
+  listClaims
+};

package/dist/chunk-FBL2T6BA.mjs

@@ -0,0 +1,249 @@
+import {
+  __objRest,
+  __spreadProps,
+  __spreadValues
+} from "./chunk-FWCSY2DS.mjs";
+
+// src/v1/core/constants.ts
+var MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+var XNET_2022_MINT = "xNETbUB7cRb3AAu2pNG2pUwQcJ2BHcktfvSB8x1Pq6L";
+var DEFAULT_RPC_ENDPOINT = process.env.NEXT_PUBLIC_SOLANA_RPC_URL || "https://api.mainnet-beta.solana.com";
+var DISTRIBUTION_MEMO_PREFIX = "dist";
+
+// src/v1/core/helpers.ts
+function buildDistributionMemoTag(distributionId, action = "claim") {
+  return `${DISTRIBUTION_MEMO_PREFIX}:${distributionId}:${action}`;
+}
+function assertTruthy(value, message) {
+  if (value === null || value === void 0) {
+    throw new Error(message);
+  }
+  return value;
+}
+
+// src/v1/core/persistence.ts
+var STORAGE_PREFIX = "distribution:persistence-warning:";
+var PERSISTENCE_WARNING_EVENT = "distribution:persistence-warning";
+function isBrowser() {
+  return typeof window !== "undefined" && typeof localStorage !== "undefined";
+}
+function persistToStorage(record) {
+  if (!isBrowser()) return;
+  try {
+    localStorage.setItem(`${STORAGE_PREFIX}${record.id}`, JSON.stringify(record));
+  } catch (error) {
+    console.error("[sync:persistence-warning] Failed to write to localStorage", error);
+  }
+}
+function emitWarning(record) {
+  if (!isBrowser()) return;
+  try {
+    window.dispatchEvent(new CustomEvent(PERSISTENCE_WARNING_EVENT, { detail: record }));
+  } catch (error) {
+    console.error("[sync:persistence-warning] Failed to emit warning event", error);
+  }
+}
+function recordPersistenceWarning(input) {
+  var _a2;
+  if (!isBrowser()) return void 0;
+  const record = __spreadProps(__spreadValues({}, input), {
+    createdAt: (_a2 = input.createdAt) != null ? _a2 : Date.now()
+  });
+  persistToStorage(record);
+  emitWarning(record);
+  return record;
+}
+function handlePersistenceWarningResponse(response) {
+  var _a2;
+  if (!isBrowser() || !response || typeof response !== "object") return;
+  const warning = response.persistenceWarning;
+  if (!warning) return;
+  const distributionId = warning.distributionId || response.distributionId || "unknown";
+  const exportJson = (_a2 = response.exportJson) != null ? _a2 : warning.exportJson;
+  const reason = warning.reason || "persist_distribution_failed";
+  const message = warning.message || "We were unable to save your distribution draft. Download the JSON to avoid data loss.";
+  const key = warning.id || `${distributionId}:${reason}:${Date.now()}`;
+  recordPersistenceWarning({
+    id: key,
+    distributionId,
+    reason,
+    message,
+    detail: warning.detail,
+    exportJson
+  });
+}
+function loadPersistenceWarnings() {
+  if (!isBrowser()) return [];
+  const records = [];
+  try {
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (!key || !key.startsWith(STORAGE_PREFIX)) continue;
+      const raw = localStorage.getItem(key);
+      if (!raw) continue;
+      try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object") {
+          records.push(parsed);
+        }
+      } catch (e) {
+      }
+    }
+  } catch (error) {
+    console.error("[sync:persistence-warning] Failed to load warnings", error);
+  }
+  return records.sort((a, b) => b.createdAt - a.createdAt);
+}
+function clearPersistenceWarning(id) {
+  if (!isBrowser()) return;
+  try {
+    localStorage.removeItem(`${STORAGE_PREFIX}${id}`);
+  } catch (e) {
+  }
+}
+
+// src/v1/core/http.ts
+var FALLBACK_BASE_PATH = "/api/v1/fractals-sync";
+var _a, _b;
+var ENV_BASE_PATH = typeof process !== "undefined" && (((_a = process.env) == null ? void 0 : _a.NEXT_PUBLIC_SYNC_PATH) || ((_b = process.env) == null ? void 0 : _b.NEXT_PUBLIC_FRACTALS_SYNC_PATH)) || void 0;
+var DEFAULT_BASE_PATH = sanitizeBasePath(ENV_BASE_PATH || FALLBACK_BASE_PATH);
+function resolveRequestConfig(options) {
+  return {
+    basePath: sanitizeBasePath((options == null ? void 0 : options.basePath) || DEFAULT_BASE_PATH),
+    fetcher: resolveFetcher(options == null ? void 0 : options.fetcher)
+  };
+}
+var SyncReactError = class extends Error {
+  constructor(status, code, details) {
+    super(code || `Sync request failed with status ${status}`);
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.name = "SyncReactError";
+  }
+};
+async function requestJSON(config, path, init) {
+  var _a2;
+  const url = buildUrl(config.basePath, path);
+  const requestInit = prepareInit(init);
+  requestInit.credentials = (_a2 = requestInit.credentials) != null ? _a2 : isRelativeUrl(url) ? "include" : void 0;
+  const response = await config.fetcher(url, requestInit);
+  const payload = await parseResponseBody(response);
+  if (!response.ok) {
+    const errorCode = typeof payload === "object" && payload && "error" in payload ? String(payload.error) : void 0;
+    throw new SyncReactError(response.status, errorCode, payload);
+  }
+  return payload;
+}
+function resolveFetcher(custom) {
+  if (custom) return custom;
+  if (typeof fetch === "function") return fetch.bind(globalThis);
+  throw new Error("Global fetch is not available. Provide a fetcher via Sync configuration.");
+}
+function sanitizeBasePath(path) {
+  if (!path) return FALLBACK_BASE_PATH;
+  const trimmed = path.trim();
+  if (!trimmed || trimmed === "/") return "/";
+  return trimmed.replace(/\/+$/, "");
+}
+function buildUrl(basePath, path) {
+  if (path && isAbsoluteUrl(path)) return path;
+  const normalizedBase = sanitizeBasePath(basePath);
+  const suffix = path ? `/${path.replace(/^\/+/, "")}` : "";
+  if (!normalizedBase || normalizedBase === "/") {
+    return suffix ? suffix : normalizedBase;
+  }
+  return `${normalizedBase}${suffix}`;
+}
+function isAbsoluteUrl(path) {
+  return /^https?:\/\//i.test(path);
+}
+function isRelativeUrl(path) {
+  return !isAbsoluteUrl(path);
+}
+function prepareInit(init) {
+  const finalInit = __spreadValues({}, init);
+  if ((init == null ? void 0 : init.headers) instanceof Headers) {
+    const cloned = new Headers(init.headers);
+    if (!cloned.has("content-type")) cloned.set("content-type", "application/json");
+    finalInit.headers = cloned;
+    return finalInit;
+  }
+  const headers = new Headers(init == null ? void 0 : init.headers);
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  finalInit.headers = headers;
+  return finalInit;
+}
+async function parseResponseBody(response) {
+  if (response.status === 204) return void 0;
+  const text = await response.text();
+  if (!text) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    return text;
+  }
+}
+
+// src/v1/core/api.ts
+async function buildDistributionTransaction(input, options) {
+  const config = resolveRequestConfig(options);
+  const path = (input == null ? void 0 : input.distributionId) ? `/distributions/${encodeURIComponent(input.distributionId)}/create-transaction` : "/distributions/create-transaction";
+  const payload = await requestJSON(config, path, {
+    method: "POST",
+    body: JSON.stringify(input)
+  });
+  handlePersistenceWarningResponse(payload);
+  return payload;
+}
+async function commitDistributionSignature(input, options) {
+  const distributionId = input == null ? void 0 : input.distributionId;
+  if (!distributionId) {
+    throw new SyncReactError(400, "distribution_id_required");
+  }
+  const config = resolveRequestConfig(options);
+  const _a2 = input, { distributionId: _unused } = _a2, body = __objRest(_a2, ["distributionId"]);
+  return requestJSON(
+    config,
+    `/distributions/${encodeURIComponent(distributionId)}/commit`,
+    {
+      method: "POST",
+      body: JSON.stringify(body)
+    }
+  );
+}
+async function prepareDistributionDraft(input, options) {
+  const config = resolveRequestConfig(options);
+  return requestJSON(config, "/distributions/prepare", {
+    method: "POST",
+    body: JSON.stringify(input)
+  });
+}
+
+export {
+  MEMO_PROGRAM_ID,
+  XNET_2022_MINT,
+  DEFAULT_RPC_ENDPOINT,
+  DISTRIBUTION_MEMO_PREFIX,
+  buildDistributionMemoTag,
+  assertTruthy,
+  PERSISTENCE_WARNING_EVENT,
+  recordPersistenceWarning,
+  handlePersistenceWarningResponse,
+  loadPersistenceWarnings,
+  clearPersistenceWarning,
+  DEFAULT_BASE_PATH,
+  resolveRequestConfig,
+  SyncReactError,
+  requestJSON,
+  resolveFetcher,
+  sanitizeBasePath,
+  buildUrl,
+  isAbsoluteUrl,
+  isRelativeUrl,
+  buildDistributionTransaction,
+  commitDistributionSignature,
+  prepareDistributionDraft
+};