@zkmedusa/passport-sdk 0.1.0 → 0.3.0

package/README.md

@@ -21,8 +21,8 @@ import {
 const passport = parsePassportJson(passportJsonFromUser);
 
 const result = verifyPassport(passport, {
-  issuerPublicKey: "749d6135f3d883950ff82f82bc2119e8b6e469ebfc4163dd10e1cc079b723565",
-  minTier: 2, // require SILVER+
+  issuerPublicKey: process.env.MEDUSA_ISSUER_PUBLIC_KEY!,
+  minTier: 2,
 });
 
 if (result.valid) {
@@ -38,19 +38,19 @@ Fetch the issuer public key dynamically:
 import { MedusaPassportClient } from "@zkmedusa/passport-sdk";
 
 const client = new MedusaPassportClient({
-  baseUrl: "https://your-medusa-app.com",
+  baseUrl: "https://www.zkmedusa.com",
 });
 
 const result = await client.verify(passport);
 ```
 
-## Register for whitelist / presale
+## Register for whitelist / presale (partner backend)
 
-Users present a passport, then link a **claim wallet** (the address that receives presale access).
+Partners register claim wallets from their backend with a Bearer API key scoped to one `campaignId`.
 
 ```typescript
 const client = new MedusaPassportClient({
-  baseUrl: "https://your-medusa-app.com",
+  baseUrl: "https://www.zkmedusa.com",
   apiKey: process.env.MEDUSA_PARTNER_API_KEY,
 });
 
@@ -67,33 +67,73 @@ Pull the whitelist for your campaign:
 
 ```typescript
 const entries = await client.getWhitelist("my-presale-q3");
-// [{ claimWallet, tier, tierLabel, nullifier, registeredAt }, ...]
 ```
 
+## Claim wallet (user flow)
+
+Since **v0.2.0**, users can register a **claim wallet** without a partner API key — for apps that let users submit their own claim address after minting a passport.
+
+No `apiKey` is required. The campaign must be enabled on the Medusa server (`MEDUSA_CLAIM_CAMPAIGN_IDS`).
+
+```typescript
+const client = new MedusaPassportClient({
+  baseUrl: "https://www.zkmedusa.com",
+});
+
+await client.registerClaimWallet({
+  passport,
+  claimWallet: "FreshClaimWalletPublicKey...",
+  campaignId: "my-presale-q3",
+});
+```
+
+Rotate to a new claim address for the same campaign (after generating a fresh wallet):
+
+```typescript
+await client.rotateClaimWallet({
+  passport,
+  claimWallet: "NewClaimWalletPublicKey...",
+  campaignId: "my-presale-q3",
+});
+```
+
+Users can also manage claim wallets in the browser at [zkmedusa.com/wallet](https://www.zkmedusa.com/wallet).
+
+**Partner vs user registration**
+
+| Method | Auth | Endpoint |
+| --- | --- | --- |
+| `client.register()` | Bearer API key | `/api/partner/register` |
+| `client.registerClaimWallet()` | None | `/api/passport/claim/register` |
+| `client.rotateClaimWallet()` | None | `/api/passport/claim/rotate` |
+
 ## Partner API keys
 
 Medusa operators create keys in `.env`:
 
 ```env
 MEDUSA_PARTNER_API_KEYS=my-presale-q3:sk_live_partner_key
+MEDUSA_CLAIM_CAMPAIGN_IDS=my-presale-q3,medusa-claim
 ```
 
-Each key is scoped to one `campaignId`.
+Each partner key is scoped to one `campaignId`. Public claim routes only accept campaign IDs listed in `MEDUSA_CLAIM_CAMPAIGN_IDS`.
 
 ## Endpoints used by the SDK
 
 | Endpoint | Purpose |
-|----------|---------|
+| --- | --- |
 | `GET /api/passport/issuer` | Issuer public key |
 | `GET /api/passport/verify` | Policy metadata |
 | `POST /api/passport/verify` | Remote passport verification |
-| `POST /api/partner/register` | Register passport + claim wallet |
+| `POST /api/partner/register` | Partner register (Bearer) |
+| `POST /api/passport/claim/register` | User claim wallet register |
+| `POST /api/passport/claim/rotate` | User claim wallet rotate |
 | `GET /api/partner/whitelist?campaignId=` | Export campaign whitelist |
 
 ## Tier gating example
 
 ```typescript
-const PRESALE_MIN_TIER = 1; // bronze
+const PRESALE_MIN_TIER = 1;
 const ALLOCATION_BY_TIER = { 1: 0.1, 2: 0.5, 3: 2 };
 
 const result = await client.verify(passport, { minTier: PRESALE_MIN_TIER });
@@ -106,8 +146,37 @@ const maxSol = ALLOCATION_BY_TIER[result.tier!];
 
 - The passport proves eligibility **without** revealing the proving wallet.
 - Registration links the passport to a **claim wallet** for whitelist/presale payout.
+- Claim wallet secret keys stay in the user's browser unless they export a backup JSON.
 - One passport nullifier can register once per campaign (anti-sybil).
 
 ## Browser + Node
 
 The SDK works in Node.js, Next.js API routes, and the browser (local verify only).
+
+## Publishing this package (maintainers)
+
+From the monorepo root:
+
+```bash
+# 1. Log in to npm (once per machine)
+npm login
+
+# 2. Build the SDK (runs automatically before publish via prepublishOnly)
+npm run build:sdk
+
+# 3. Publish to npm
+npm run publish:sdk
+```
+
+Or from `packages/medusa-passport-sdk/`:
+
+```bash
+npm run build
+npm publish --access public
+```
+
+Bump `version` in `packages/medusa-passport-sdk/package.json` before each publish (semver). After publishing, integrators update with:
+
+```bash
+npm install @zkmedusa/passport-sdk@latest
+```

package/dist/badges.d.ts

@@ -0,0 +1,46 @@
+import { type PassportTier } from "./types.js";
+export interface PassportBadge {
+    /** MPL Core asset address of the soulbound badge. */
+    assetId: string;
+    owner: string;
+    collection: string | null;
+    /** True when the asset is permanently frozen (soulbound). */
+    frozen: boolean;
+    name?: string;
+    tier?: PassportTier;
+    tierLabel?: string;
+    expiresAt?: string;
+    nullifier?: string;
+    /** Raw DAS asset object for advanced consumers. */
+    raw: unknown;
+}
+export interface FetchPassportBadgesOptions {
+    /**
+     * A Solana RPC endpoint that supports the DAS (Digital Asset Standard) API,
+     * e.g. Helius/Triton/QuickNode. Required to read MPL Core assets by owner.
+     */
+    dasRpcUrl: string;
+    /** Only return badges that belong to this collection address. */
+    collection?: string;
+    /** Only return badges at or above this tier. */
+    minTier?: PassportTier;
+    /** Only return permanently-frozen (soulbound) badges. Defaults to true. */
+    requireFrozen?: boolean;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Reads the soulbound Medusa passport badges (MPL Core assets) owned by a
+ * wallet using the DAS API. Use this to gate access by on-chain badge instead
+ * of (or in addition to) verifying a signed passport credential.
+ *
+ * Note: the authoritative tier is always the signed passport; on-chain
+ * attributes are a convenience mirror that depends on your DAS provider
+ * exposing MPL Core attributes.
+ */
+export declare function fetchPassportBadges(owner: string, options: FetchPassportBadgesOptions): Promise<PassportBadge[]>;
+/**
+ * Convenience predicate: returns true when the wallet holds at least one
+ * soulbound Medusa passport badge meeting the supplied options.
+ */
+export declare function hasPassportBadge(owner: string, options: FetchPassportBadgesOptions): Promise<boolean>;
+//# sourceMappingURL=badges.d.ts.map

package/dist/badges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"badges.d.ts","sourceRoot":"","sources":["../src/badges.ts"],"names":[],"mappings":"AACA,OAAO,EAA+B,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5E,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAmID;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,aAAa,EAAE,CAAC,CA+D1B;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/badges.js

@@ -0,0 +1,171 @@
+import { MedusaPassportError } from "./errors.js";
+import { PASSPORT_TIERS, TIER_LABELS } from "./types.js";
+const TIER_FROM_LABEL = {
+    [TIER_LABELS[PASSPORT_TIERS.BRONZE]]: PASSPORT_TIERS.BRONZE,
+    [TIER_LABELS[PASSPORT_TIERS.SILVER]]: PASSPORT_TIERS.SILVER,
+    [TIER_LABELS[PASSPORT_TIERS.GOLD]]: PASSPORT_TIERS.GOLD,
+};
+function asRecord(value) {
+    return value && typeof value === "object"
+        ? value
+        : undefined;
+}
+/**
+ * MPL Core attributes can surface in a few shapes across DAS providers, so we
+ * read defensively from all of them and normalize to a flat key/value map.
+ */
+function readAttributes(item) {
+    const out = {};
+    const content = asRecord(item.content);
+    const metadata = content ? asRecord(content.metadata) : undefined;
+    const plugins = asRecord(item.plugins);
+    const attributesPlugin = plugins ? asRecord(plugins.attributes) : undefined;
+    const attributesPluginData = attributesPlugin
+        ? asRecord(attributesPlugin.data)
+        : undefined;
+    const mplCoreInfo = asRecord(item.mpl_core_info);
+    const sources = [
+        item.attributes,
+        metadata?.attributes,
+        attributesPluginData?.attribute_list,
+        mplCoreInfo?.attributes,
+    ];
+    for (const source of sources) {
+        if (!Array.isArray(source)) {
+            continue;
+        }
+        for (const entry of source) {
+            const record = asRecord(entry);
+            if (!record) {
+                continue;
+            }
+            const key = record.key ?? record.trait_type;
+            const value = record.value;
+            if (typeof key === "string" && value != null) {
+                out[key.toLowerCase()] = String(value);
+            }
+        }
+    }
+    return out;
+}
+function tierFromAttributes(attrs) {
+    const label = attrs.tier?.toUpperCase();
+    if (label && label in TIER_FROM_LABEL) {
+        return TIER_FROM_LABEL[label];
+    }
+    const level = Number(attrs.tierlevel);
+    if (level === 1 || level === 2 || level === 3) {
+        return level;
+    }
+    return undefined;
+}
+function collectionFromGrouping(item) {
+    const grouping = item.grouping;
+    if (!Array.isArray(grouping)) {
+        return null;
+    }
+    for (const entry of grouping) {
+        const record = asRecord(entry);
+        if (record && record.group_key === "collection") {
+            return typeof record.group_value === "string"
+                ? record.group_value
+                : null;
+        }
+    }
+    return null;
+}
+function isFrozen(item) {
+    const ownership = asRecord(item.ownership);
+    if (ownership && typeof ownership.frozen === "boolean") {
+        return ownership.frozen;
+    }
+    const plugins = asRecord(item.plugins);
+    const permanentFreeze = plugins
+        ? asRecord(plugins.permanent_freeze_delegate ?? plugins.permanentFreezeDelegate)
+        : undefined;
+    const data = permanentFreeze ? asRecord(permanentFreeze.data) : undefined;
+    return data?.frozen === true;
+}
+function toBadge(item) {
+    const attrs = readAttributes(item);
+    const content = asRecord(item.content);
+    const metadata = content ? asRecord(content.metadata) : undefined;
+    const tier = tierFromAttributes(attrs);
+    return {
+        assetId: typeof item.id === "string" ? item.id : "",
+        owner: asRecord(item.ownership)?.owner ?? "",
+        collection: collectionFromGrouping(item),
+        frozen: isFrozen(item),
+        name: metadata?.name ??
+            (typeof item.name === "string" ? item.name : undefined),
+        tier,
+        tierLabel: tier ? TIER_LABELS[tier] : attrs.tier?.toUpperCase(),
+        expiresAt: attrs.expiresat,
+        nullifier: attrs.nullifier,
+        raw: item,
+    };
+}
+/**
+ * Reads the soulbound Medusa passport badges (MPL Core assets) owned by a
+ * wallet using the DAS API. Use this to gate access by on-chain badge instead
+ * of (or in addition to) verifying a signed passport credential.
+ *
+ * Note: the authoritative tier is always the signed passport; on-chain
+ * attributes are a convenience mirror that depends on your DAS provider
+ * exposing MPL Core attributes.
+ */
+export async function fetchPassportBadges(owner, options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const requireFrozen = options.requireFrozen ?? true;
+    const response = await fetchImpl(options.dasRpcUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: "medusa-badges",
+            method: "getAssetsByOwner",
+            params: {
+                ownerAddress: owner,
+                page: 1,
+                limit: 1000,
+            },
+        }),
+    });
+    if (!response.ok) {
+        throw new MedusaPassportError(`DAS request failed with status ${response.status}.`, "API_ERROR");
+    }
+    const payload = (await response.json());
+    if (payload.error) {
+        throw new MedusaPassportError(payload.error.message ?? "DAS request returned an error.", "API_ERROR");
+    }
+    const items = payload.result?.items ?? [];
+    return items
+        .map(asRecord)
+        .filter((item) => Boolean(item))
+        .filter((item) => {
+        const iface = item.interface;
+        return iface === undefined || iface === "MplCoreAsset";
+    })
+        .map(toBadge)
+        .filter((badge) => {
+        if (options.collection && badge.collection !== options.collection) {
+            return false;
+        }
+        if (requireFrozen && !badge.frozen) {
+            return false;
+        }
+        if (options.minTier !== undefined &&
+            (badge.tier === undefined || badge.tier < options.minTier)) {
+            return false;
+        }
+        return true;
+    });
+}
+/**
+ * Convenience predicate: returns true when the wallet holds at least one
+ * soulbound Medusa passport badge meeting the supplied options.
+ */
+export async function hasPassportBadge(owner, options) {
+    const badges = await fetchPassportBadges(owner, options);
+    return badges.length > 0;
+}

package/dist/client.d.ts

@@ -1,4 +1,5 @@
-import type { IssuerInfo, MedusaPassport, PassportPolicy, RegisterPassportInput, RegisterPassportResult, VerifyPassportOptions, VerifyPassportResult, WhitelistEntry } from "./types.js";
+import { type FetchPassportBadgesOptions, type PassportBadge } from "./badges.js";
+import type { IssuerInfo, MedusaPassport, PassportPolicy, RegisterPassportInput, RegisterPassportResult, ClaimRegisterInput, ClaimRegisterResult, ClaimRotateInput, ClaimRotateResult, VerifyPassportOptions, VerifyPassportResult, WhitelistEntry } from "./types.js";
 export interface MedusaPassportClientOptions {
     baseUrl: string;
     apiKey?: string;
@@ -18,7 +19,11 @@ export declare class MedusaPassportClient {
     verifyLocal(passport: MedusaPassport, options: VerifyPassportOptions): VerifyPassportResult;
     parseAndVerify(passportJson: string, options?: Omit<VerifyPassportOptions, "issuerPublicKey">): Promise<VerifyPassportResult>;
     register(input: RegisterPassportInput): Promise<RegisterPassportResult>;
+    registerClaimWallet(input: ClaimRegisterInput): Promise<ClaimRegisterResult>;
+    rotateClaimWallet(input: ClaimRotateInput): Promise<ClaimRotateResult>;
     getWhitelist(campaignId: string): Promise<WhitelistEntry[]>;
+    getBadges(owner: string, options: FetchPassportBadgesOptions): Promise<PassportBadge[]>;
+    hasBadge(owner: string, options: FetchPassportBadgesOptions): Promise<boolean>;
     hasValidSignature(passport: MedusaPassport, issuerPublicKey?: string): boolean;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE,2BAA2B;IAO1C,WAAW,IAAI,OAAO,CAAC,UAAU,CAAC;IAelC,WAAW,IAAI,OAAO,CAAC,cAAc,CAAC;IAUtC,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA+BrE,MAAM,CACV,QAAQ,EAAE,cAAc,EACxB,OAAO,GAAE,IAAI,CAAC,qBAAqB,EAAE,iBAAiB,CAAM,GAC3D,OAAO,CAAC,oBAAoB,CAAC;IAehC,WAAW,CACT,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,qBAAqB,GAC7B,oBAAoB;IAIjB,cAAc,CAClB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,IAAI,CAAC,qBAAqB,EAAE,iBAAiB,CAAM,GAC3D,OAAO,CAAC,oBAAoB,CAAC;IAiB1B,QAAQ,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA+BvE,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAgCjE,iBAAiB,CAAC,QAAQ,EAAE,cAAc,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO;CAQ/E"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,0BAA0B,EAC/B,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAMrB,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE,2BAA2B;IAO1C,WAAW,IAAI,OAAO,CAAC,UAAU,CAAC;IAelC,WAAW,IAAI,OAAO,CAAC,cAAc,CAAC;IAUtC,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA+BrE,MAAM,CACV,QAAQ,EAAE,cAAc,EACxB,OAAO,GAAE,IAAI,CAAC,qBAAqB,EAAE,iBAAiB,CAAM,GAC3D,OAAO,CAAC,oBAAoB,CAAC;IAehC,WAAW,CACT,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,qBAAqB,GAC7B,oBAAoB;IAIjB,cAAc,CAClB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,IAAI,CAAC,qBAAqB,EAAE,iBAAiB,CAAM,GAC3D,OAAO,CAAC,oBAAoB,CAAC;IAiB1B,QAAQ,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA+BvE,mBAAmB,CACvB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,mBAAmB,CAAC;IAwBzB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwBtE,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAgC3D,SAAS,CACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,aAAa,EAAE,CAAC;IAOrB,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,OAAO,CAAC;IAOnB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO;CAQ/E"}

package/dist/client.js

@@ -1,4 +1,5 @@
 import { MedusaPassportError } from "./errors.js";
+import { fetchPassportBadges, hasPassportBadge, } from "./badges.js";
 import { parsePassportJson, verifyPassport, verifyPassportSignature, } from "./verify.js";
 export class MedusaPassportClient {
     constructor(options) {
@@ -93,6 +94,30 @@ export class MedusaPassportClient {
         }
         return payload;
     }
+    async registerClaimWallet(input) {
+        const response = await this.fetchImpl(`${this.baseUrl}/api/passport/claim/register`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(input),
+        });
+        const payload = (await response.json());
+        if (!response.ok || !payload.registered) {
+            throw new MedusaPassportError(payload.error ?? "Claim wallet registration failed.", "REGISTRATION_FAILED");
+        }
+        return payload;
+    }
+    async rotateClaimWallet(input) {
+        const response = await this.fetchImpl(`${this.baseUrl}/api/passport/claim/rotate`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(input),
+        });
+        const payload = (await response.json());
+        if (!response.ok || !payload.rotated) {
+            throw new MedusaPassportError(payload.error ?? "Claim wallet rotation failed.", "REGISTRATION_FAILED");
+        }
+        return payload;
+    }
     async getWhitelist(campaignId) {
         if (!this.apiKey) {
             throw new MedusaPassportError("apiKey is required to fetch whitelist entries.", "API_ERROR");
@@ -108,6 +133,18 @@ export class MedusaPassportClient {
         }
         return payload.entries ?? [];
     }
+    async getBadges(owner, options) {
+        return fetchPassportBadges(owner, {
+            fetchImpl: this.fetchImpl,
+            ...options,
+        });
+    }
+    async hasBadge(owner, options) {
+        return hasPassportBadge(owner, {
+            fetchImpl: this.fetchImpl,
+            ...options,
+        });
+    }
     hasValidSignature(passport, issuerPublicKey) {
         const key = issuerPublicKey ?? this.issuerPublicKey;
         if (!key) {

package/dist/index.d.ts

@@ -2,7 +2,9 @@ export { MedusaPassportClient } from "./client.js";
 export type { MedusaPassportClientOptions } from "./client.js";
 export { MedusaPassportError } from "./errors.js";
 export { PASSPORT_POLICY_VERSION, PASSPORT_TIERS, TIER_LABELS, } from "./types.js";
-export type { IssuerInfo, MedusaPassport, PassportPolicy, PassportPublicInputs, PassportStatement, PassportTier, RegisterPassportInput, RegisterPassportResult, VerifyPassportOptions, VerifyPassportResult, WhitelistEntry, ZkProofBundle, } from "./types.js";
+export type { IssuerInfo, MedusaPassport, PassportPolicy, PassportPublicInputs, PassportStatement, PassportTier, RegisterPassportInput, RegisterPassportResult, ClaimRegisterInput, ClaimRegisterResult, ClaimRotateInput, ClaimRotateResult, VerifyPassportOptions, VerifyPassportResult, WhitelistEntry, ZkProofBundle, } from "./types.js";
 export { hexToBytes, isValidSolanaAddress } from "./utils.js";
 export { parsePassportJson, verifyPassport, verifyPassportSignature, } from "./verify.js";
+export { fetchPassportBadges, hasPassportBadge } from "./badges.js";
+export type { PassportBadge, FetchPassportBadgesOptions } from "./badges.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,uBAAuB,GACxB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,aAAa,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -3,3 +3,4 @@ export { MedusaPassportError } from "./errors.js";
 export { PASSPORT_POLICY_VERSION, PASSPORT_TIERS, TIER_LABELS, } from "./types.js";
 export { hexToBytes, isValidSolanaAddress } from "./utils.js";
 export { parsePassportJson, verifyPassport, verifyPassportSignature, } from "./verify.js";
+export { fetchPassportBadges, hasPassportBadge } from "./badges.js";

package/dist/types.d.ts

@@ -29,7 +29,7 @@ export interface PassportStatement {
 }
 export interface MedusaPassport {
     type: "medusa_passport_v1";
-    chain: "solana";
+    chain: "solana" | "ethereum" | "base" | "bnb" | "robinhood";
     statement: PassportStatement;
     nullifier: string;
     zkProof: ZkProofBundle;
@@ -66,6 +66,35 @@ export interface RegisterPassportResult {
     nullifier: string;
     registeredAt: string;
 }
+export interface ClaimRegisterInput {
+    passport: MedusaPassport;
+    claimWallet: string;
+    campaignId?: string;
+}
+export interface ClaimRegisterResult {
+    registered: boolean;
+    campaignId: string;
+    claimWallet: string;
+    tier: PassportTier;
+    tierLabel: string;
+    nullifier: string;
+    registeredAt: string;
+}
+export interface ClaimRotateInput {
+    passport: MedusaPassport;
+    claimWallet: string;
+    campaignId?: string;
+}
+export interface ClaimRotateResult {
+    rotated: boolean;
+    previousClaimWallet: string;
+    campaignId: string;
+    claimWallet: string;
+    tier: PassportTier;
+    tierLabel: string;
+    nullifier: string;
+    registeredAt: string;
+}
 export interface WhitelistEntry {
     campaignId: string;
     claimWallet: string;

package/dist/types.d.ts.map

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

package/dist/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AAoBpB,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAc/D;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,cAAc,EACxB,eAAe,EAAE,MAAM,GACtB,OAAO,CAST;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,cAAc,EACxB,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CA8CtB"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AAqBpB,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAc/D;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,cAAc,EACxB,eAAe,EAAE,MAAM,GACtB,OAAO,CAST;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,cAAc,EACxB,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CA8CtB"}

package/dist/verify.js

@@ -6,8 +6,9 @@ function isPassportShape(value) {
         return false;
     }
     const passport = value;
+    const validChains = ["solana", "ethereum", "base", "bnb", "robinhood"];
     return (passport.type === "medusa_passport_v1" &&
-        passport.chain === "solana" &&
+        validChains.includes(passport.chain) &&
         passport.issuer === "medusa" &&
         typeof passport.signature === "string" &&
         typeof passport.nullifier === "string" &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zkmedusa/passport-sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Verify and register Medusa Passports in third-party apps, presales, and whitelists.",
   "license": "MIT",
   "type": "module",