@neus/sdk 1.1.0 → 1.1.1

package/sponsor.js

@@ -0,0 +1,95 @@
+import { ValidationError, ApiError, NetworkError } from './errors.js';
+
+/**
+ * Request short-lived billing authorization so verification usage bills the app owner.
+ * Requires a completed app registration (`sponsor-grants` delegation) on orgWallet.
+ */
+export async function fetchSponsorGrant(params = {}) {
+  const {
+    apiUrl = 'https://api.neus.network',
+    appId,
+    orgWallet,
+    verifierIds = [],
+    targetChains = [],
+    origin,
+    expiresInSeconds = 900,
+    fetchImpl = fetch
+  } = params;
+
+  const normalizedAppId = typeof appId === 'string' ? appId.trim() : '';
+  const normalizedOrg = typeof orgWallet === 'string' ? orgWallet.trim().toLowerCase() : '';
+  if (!normalizedAppId) {
+    throw new ValidationError('appId is required for sponsor grant');
+  }
+  if (!normalizedOrg || !/^0x[a-f0-9]{40}$/.test(normalizedOrg)) {
+    throw new ValidationError('orgWallet must be a valid EVM address');
+  }
+
+  let base = String(apiUrl || 'https://api.neus.network').replace(/\/+$/, '');
+  try {
+    const url = new URL(base);
+    if (url.hostname.endsWith('neus.network') && url.protocol === 'http:') {
+      url.protocol = 'https:';
+    }
+    base = url.toString().replace(/\/+$/, '');
+  } catch {
+    void 0;
+  }
+
+  const headers = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    'X-Neus-App': normalizedAppId,
+    'X-Neus-Sdk': 'js'
+  };
+  if (typeof origin === 'string' && origin.trim()) {
+    headers.Origin = origin.trim();
+  }
+
+  const body = {
+    orgWallet: normalizedOrg,
+    scope: 'sponsored-verification',
+    expiresInSeconds,
+    ...(Array.isArray(verifierIds) && verifierIds.length > 0
+      ? { verifierIds: verifierIds.map((v) => String(v).trim()).filter(Boolean).slice(0, 25) }
+      : {}),
+    ...(Array.isArray(targetChains) && targetChains.length > 0
+      ? { targetChains: targetChains.filter((n) => Number.isFinite(Number(n))).slice(0, 25) }
+      : {})
+  };
+
+  let response;
+  try {
+    response = await fetchImpl(`${base}/api/v1/sponsor/grant`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body)
+    });
+  } catch (error) {
+    throw new NetworkError(`Sponsor grant request failed: ${error?.message || String(error)}`);
+  }
+
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    payload = { success: false, error: { message: 'Invalid JSON response' } };
+  }
+
+  if (!response.ok || payload?.success !== true) {
+    throw ApiError.fromResponse(response, payload);
+  }
+
+  const token = payload?.data?.sponsorGrant;
+  if (!token || typeof token !== 'string') {
+    throw new ApiError('Sponsor grant response missing sponsorGrant token', payload?.error);
+  }
+
+  return {
+    sponsorGrant: token,
+    exp: payload?.data?.exp,
+    orgWallet: payload?.data?.orgWallet || normalizedOrg,
+    appId: payload?.data?.appId || normalizedAppId,
+    maxCredits: payload?.data?.maxCredits
+  };
+}

package/types.d.ts

@@ -57,9 +57,18 @@ declare module '@neus/sdk' {
 
   export interface NeusClientConfig {
     apiUrl?: string;
+    /** Optional server profile key — MCP/CI only; not required for VerifyGate or gateCheck. */
     apiKey?: string;
+    /** Public app attribution id (non-secret). */
     appId?: string;
-    /** Optional: only when using legacy `delegationQHash` on verify requests. App-linked servers rely on `appId` + Origin + stored delegation. */
+    /** Hub wallet that pays for user verification checks (your NEUS account). */
+    billingWallet?: string;
+    /** Alias for billingWallet. */
+    sponsorOrgWallet?: string;
+    orgWallet?: string;
+    /** Site origin used when issuing billing authorization (defaults to browser origin). */
+    appOrigin?: string;
+    /** @deprecated Advanced server path only — use appId + billingWallet for the default app flow. */
     appLinkQHash?: string;
     paymentSignature?: string;
     extraHeaders?: Record<string, string>;
@@ -68,6 +77,26 @@ declare module '@neus/sdk' {
     enableLogging?: boolean;
   }
 
+  export interface FetchSponsorGrantParams {
+    apiUrl?: string;
+    appId: string;
+    orgWallet: string;
+    verifierIds?: string[];
+    targetChains?: number[];
+    origin?: string;
+    expiresInSeconds?: number;
+  }
+
+  export interface FetchSponsorGrantResult {
+    sponsorGrant: string;
+    exp?: number;
+    orgWallet: string;
+    appId: string;
+    maxCredits?: number;
+  }
+
+  export function fetchSponsorGrant(params: FetchSponsorGrantParams): Promise<FetchSponsorGrantResult>;
+
   export interface VerificationOptions {
     privacyLevel?: PrivacyLevel;
     enableIpfs?: boolean;

package/utils.js

@@ -1023,6 +1023,8 @@ export function getHostedCheckoutUrl(opts = {}) {
   if (opts.intent) params.set('intent', String(opts.intent));
   if (opts.origin) params.set('origin', String(opts.origin));
   if (opts.oauthProvider) params.set('oauthProvider', String(opts.oauthProvider));
+  if (opts.appId) params.set('appId', String(opts.appId));
+  if (opts.billingWallet) params.set('billingWallet', String(opts.billingWallet).trim().toLowerCase());
   const qs = params.toString();
   return qs ? `${base}?${qs}` : base;
 }

package/widgets/README.md

@@ -35,7 +35,7 @@ export function Page() {
 ```jsx
 import { ProofBadge } from '@neus/sdk/widgets';
 
-<ProofBadge qHash="0x..." showChains />
+<ProofBadge qHash={proof.qHash} showChains />
 ```
 
 ## Docs

package/widgets/verify-gate/dist/VerifyGate.js

@@ -13,13 +13,25 @@ function buildHostedCheckoutUrl({
   origin,
   oauthProvider,
   campaignTitle,
-  campaignMessage
+  campaignMessage,
+  appId,
+  billingWallet,
+  gateId
 }) {
   const checkoutUrl = new URL(hostedCheckoutUrl);
   checkoutUrl.searchParams.set("verifiers", verifierList.join(","));
   checkoutUrl.searchParams.set("mode", "popup");
   checkoutUrl.searchParams.set("returnUrl", returnUrl);
   checkoutUrl.searchParams.set("origin", origin);
+  if (typeof appId === "string" && appId.trim()) {
+    checkoutUrl.searchParams.set("appId", appId.trim());
+  }
+  if (typeof billingWallet === "string" && billingWallet.trim()) {
+    checkoutUrl.searchParams.set("billingWallet", billingWallet.trim().toLowerCase());
+  }
+  if (typeof gateId === "string" && gateId.trim()) {
+    checkoutUrl.searchParams.set("gateId", gateId.trim());
+  }
   if (typeof oauthProvider === "string" && oauthProvider.trim()) {
     checkoutUrl.searchParams.set("oauthProvider", oauthProvider.trim());
   }
@@ -186,6 +198,7 @@ function VerifyGate({
   onVerified = void 0,
   apiUrl = void 0,
   appId = void 0,
+  billingWallet = void 0,
   paymentSignature = void 0,
   extraHeaders = void 0,
   hostedCheckoutUrl = void 0,
@@ -220,8 +233,8 @@ function VerifyGate({
   const [existingProofs, setExistingProofs] = useState(null);
   const [operation, setOperation] = useState("verify");
   const client = useMemo(
-    () => new NeusClient({ apiUrl, appId, paymentSignature, extraHeaders }),
-    [apiUrl, appId, paymentSignature, extraHeaders]
+    () => new NeusClient({ apiUrl, appId, billingWallet, paymentSignature, extraHeaders }),
+    [apiUrl, appId, billingWallet, paymentSignature, extraHeaders]
   );
   const verifierList = useMemo(() => {
     return Array.isArray(requiredVerifiers) && requiredVerifiers.length > 0 ? requiredVerifiers : ["ownership-basic"];
@@ -397,7 +410,9 @@ function VerifyGate({
       origin,
       oauthProvider,
       campaignTitle,
-      campaignMessage
+      campaignMessage,
+      appId,
+      billingWallet
     });
     let expectedOrigin = null;
     try {
@@ -451,7 +466,7 @@ function VerifyGate({
       };
       window.addEventListener("message", onMessage);
     });
-  }, [resolvedHostedCheckoutUrl, verifierList, oauthProvider, campaignTitle, campaignMessage]);
+  }, [resolvedHostedCheckoutUrl, verifierList, oauthProvider, campaignTitle, campaignMessage, appId, billingWallet]);
   useEffect(() => {
     onStateChange?.(state);
   }, [state, onStateChange]);

package/CHANGELOG.md

@@ -1,3 +0,0 @@
-# Changelog
-
-Release notes: [github.com/neus/network/blob/main/CHANGELOG.md](https://github.com/neus/network/blob/main/CHANGELOG.md)