@fractalshq/sync

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          // 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/
│   ├── 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

import { listClaims, buildClaimTransaction } from "@fractalshq/sync/v2/core";

const claims = await listClaims(wallet);
const tx = await buildClaimTransaction({
  distributionId,
  claimant: wallet,
});

React usage

import { useClaims, useClaimTransaction } from "@fractalshq/sync/v2/react";

const claimsQuery = useClaims(wallet);
const buildTx = useClaimTransaction();
buildTx.mutateAsync({ distributionId, claimant: wallet });

UI-only flow (bring your own signer)

V2 is build-only: it returns a transaction payload and you wire signing/sending yourself. Show the signature optimistically, then rely on eventual consistency for history.

import { useClaimTransaction } from "@fractalshq/sync/v2/react";

const buildTx = useClaimTransaction();

async function handleClaim(item: { distributorId: string }, wallet: string) {
  const payload = await buildTx.mutateAsync({
    distributionId: item.distributorId,
    claimant: wallet,
  });

  // App-owned: build a Transaction from payload.transaction (base64) or payload.instructions.
  const tx = buildTransactionFromPayload(payload);
  const signed = await signTransaction(tx);
  const signature = await connection.sendRawTransaction(signed.serialize());

  // UI-owned: optimistic link + pending state until the next refresh.
  setOptimisticSignature(signature);
}

Notes:

• Default base path is https://sync.fractals.fun/api/v2 (override via NEXT_PUBLIC_SYNC_V2_PATH).
• For other environments, set NEXT_PUBLIC_SYNC_V2_PATH to an absolute /api/v2 base URL.
• 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.