@nibgate/sdk 0.1.1 → 0.1.3

package/README.md

@@ -17,6 +17,8 @@ import { createCircleGatewayServer, createNibgateServer } from '@nibgate/sdk/ser
 
 This works with Next.js, React apps with an API backend, Express, NestJS, Remix, SvelteKit, Astro SSR, custom servers, and CMS/plugin environments. Plain HTML can use the widget and browser events, but real gating still requires a server, edge function, API route, or signed file endpoint.
 
+Agents integrating Nibgate should read [`SKILL.md`](./SKILL.md) or the public copy at [https://nibgate.xyz/skill.md](https://nibgate.xyz/skill.md) for the compact operating guide.
+
 ## Usage
 
 First paste the widget script from your Nibgate dashboard into your site:
@@ -164,6 +166,7 @@ const premiumGuide = {
 let lastPayment = null;
 
 const rating = createOnchainRating(premiumGuide, {
+  // Optional on Arc Testnet. The SDK defaults to NIBGATE_REPUTATION_CONTRACT.
   contractAddress: process.env.NEXT_PUBLIC_NIBGATE_REPUTATION_CONTRACT,
   siteId: process.env.NEXT_PUBLIC_NIBGATE_SITE_ID,
   token: process.env.NEXT_PUBLIC_NIBGATE_SITE_TOKEN,
@@ -192,6 +195,8 @@ createEvmGatewayUnlock(premiumGuide, {
 
 The lower-level `rateContentOnchain(resource, options)` function is also exported for custom UIs.
 
+The SDK exports the current Arc Testnet reputation deployment as `NIBGATE_REPUTATION_CONTRACT`, plus `NIBGATE_REPUTATION_CHAIN_ID`, `NIBGATE_REPUTATION_CHAIN_NAME`, and `NIBGATE_REPUTATION_RPC_URL`. Pass `contractAddress` only when overriding the default deployment.
+
 Ratings are proof-gated. Page views, time spent, scroll depth, and referrers are analytics signals; they should not become trust by themselves. Reputation-critical inputs use indexed onchain rating proofs. Signed ratings remain available only for local tests and migration tooling.
 
 Nibgate reputation uses a versioned content identity:

package/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: nibgate-sdk
+description: Use when integrating, auditing, documenting, or modifying creator-owned paid content flows with the @nibgate/sdk package. Covers installing the package, adding the Nibgate widget, defining resources, protecting server routes, emitting content/unlock events, creating nibgate.json discovery metadata, wiring Circle Gateway/x402 one-time unlocks, and avoiding fake payment or client-only gating patterns.
+---
+
+# Nibgate SDK
+
+Use `@nibgate/sdk` in the creator-owned site that actually serves the content. Nibgate Hub verifies the site, indexes public metadata, and records events; the creator site keeps the protected payload and payment receiver logic.
+
+## Install
+
+```bash
+npm install @nibgate/sdk
+```
+
+Use browser helpers from `@nibgate/sdk` and access enforcement from `@nibgate/sdk/server`:
+
+```ts
+import { checkResourceAccess, setupResourcePage, trackResourcePage } from '@nibgate/sdk'
+import { createCircleGatewayServer, manifestResponse } from '@nibgate/sdk/server'
+```
+
+## Site Widget
+
+Paste the dashboard widget into the verified site layout:
+
+```html
+<script async src="https://nibgate.xyz/widget.js"
+  data-nibgate-site="site_..."
+  data-nibgate-token="ngv_..."
+  data-nibgate-api="https://api.nibgate.xyz">
+</script>
+```
+
+The widget proves ownership and receives browser-side content, view, unlock, receipt, and reputation events. If the widget loads after app code, package events queue and flush when ready.
+
+## Resource Shape
+
+Define one stable resource per paid route, CMS row, media item, file, or API product:
+
+```ts
+const resource = {
+  id: post.id,
+  title: post.title,
+  description: post.excerpt,
+  type: 'article',
+  price: '0.01',
+  currency: 'USDC',
+  recipient: post.creatorWallet,
+  path: `/posts/${post.slug}`,
+  url: `https://creator.example/posts/${post.slug}`,
+  tags: ['essay', 'research'],
+  access: { humans: 'paid', agents: 'paid' },
+  unlock: { mode: 'one_time' }
+}
+```
+
+Allowed public content types are `article`, `image`, `music`, and `video`. Use stable external ids; changing ids breaks continuity for Explore, receipts, and reputation.
+
+## Discovery Metadata
+
+Expose public metadata at `/nibgate.json`:
+
+```ts
+import { manifestResponse } from '@nibgate/sdk/server'
+
+export function GET() {
+  return manifestResponse({
+    origin: process.env.NIBGATE_SITE_ORIGIN,
+    resources: [resource]
+  })
+}
+```
+
+Never include the protected payload in `nibgate.json`. It is only for public cards, indexing, and agent-readable discovery.
+
+## Browser Page Wiring
+
+Track the resource page and wire unlock UI:
+
+```ts
+import { setupResourcePage, trackResourcePage } from '@nibgate/sdk'
+
+trackResourcePage(resource, { source: 'creator-site' })
+
+setupResourcePage(resource, {
+  source: 'creator-site',
+  accessPath: '/api/nibgate/access',
+  payPath: '/api/nibgate/pay',
+  button: '[data-nibgate-unlock]',
+  status: '[data-nibgate-status]',
+  createPaymentSignature: walletGatewayAdapter.pay
+})
+```
+
+For custom flows, use `checkResourceAccess(resource, options)` directly. The browser can start checkout and report state, but the server must verify payment and issue unlock proof before returning protected content.
+
+## Server Access Route
+
+Protect paid content in a server route, API handler, middleware, guard, or signed file endpoint:
+
+```ts
+import { createCircleGatewayServer } from '@nibgate/sdk/server'
+
+const nibgate = createCircleGatewayServer({
+  origin: process.env.NIBGATE_SITE_ORIGIN,
+  secret: process.env.NIBGATE_SECRET,
+  network: process.env.NIBGATE_PAYMENT_NETWORK || 'eip155:5042002'
+})
+
+export function GET(request: Request) {
+  return nibgate.accessResponse(request, resource, {
+    getContent: async () => new Response(protectedHtml, {
+      headers: { 'content-type': 'text/html; charset=utf-8' }
+    })
+  })
+}
+```
+
+The route should return a real `402 Payment Required` challenge until the request has a valid payment proof or signed unlock proof.
+
+## Required Env Vars
+
+Creator site:
+
+```bash
+NIBGATE_SITE_ORIGIN=https://creator.example
+NIBGATE_SITE_ID=site_...
+NIBGATE_SITE_TOKEN=ngv_...
+NIBGATE_API_BASE=https://api.nibgate.xyz
+NIBGATE_SECRET=server_only_unlock_secret
+NIBGATE_PAYMENT_MODE=circle-gateway
+NIBGATE_PAYMENT_NETWORK=eip155:5042002
+NIBGATE_SELLER_ADDRESS=0xCreatorReceiver
+```
+
+Only expose values with `NEXT_PUBLIC_` or client-side env names when they are intentionally public, such as site id, public token, API base, or reputation contract address. Never ship `NIBGATE_SECRET`, private keys, R2 credentials, Resend keys, database URLs, or privileged payment credentials to browser code.
+
+## Payments
+
+For v1, treat `unlock.mode: 'one_time'` with Circle Gateway/x402 as the production path. A Gateway/x402 payment signature is a payment proof. A normal wallet message signature is not payment.
+
+Use `NIBGATE_BUYER_PRIVATE_KEY` only in local demos or controlled tests. In production, the visitor or agent wallet signs/pays the returned `PAYMENT-REQUIRED` challenge.
+
+## Reputation
+
+After a verified unlock, rating UI can submit onchain ratings for the same resource. Reputation-critical inputs should be tied to unlock/payment proof and indexed from chain activity. Page views, scroll depth, and referrers are analytics signals, not trust by themselves.
+
+## Never Do These
+
+- Do not hide paid HTML with CSS or client state after rendering it publicly.
+- Do not fake payment ids, receipts, unlocks, or successful access.
+- Do not replace Gateway/x402 payment signatures with ordinary wallet message signatures.
+- Do not store backend secrets in browser env vars.
+- Do not let mutable titles or slugs be the only resource identity.
+- Do not expose private content in `nibgate.json`, meta tags, JSON-LD, page source, or static builds.
+
+## Framework Notes
+
+- **Next.js**: use route handlers for `/nibgate.json` and `/api/nibgate/access`; protect content before rendering paid payloads.
+- **Express/NestJS**: use middleware, controllers, or guards around protected routes.
+- **Astro/SvelteKit/Remix**: use SSR/server routes or endpoints; plain static builds need a protected API or signed URL for private payloads.
+- **CMS apps**: save Nibgate resource settings beside each content record, including type, price, currency, receiver wallet, access policy, unlock mode, and discovery preference.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nibgate/sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Framework-agnostic browser and server package for creator-owned gated content, unlock events, and receipts.",
   "type": "module",
   "sideEffects": false,
@@ -39,7 +39,8 @@
   },
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "SKILL.md"
   ],
   "keywords": [
     "nibgate",

package/src/browser/index.js

@@ -75,7 +75,7 @@ export function rateResource(resource, rating = {}, extra = {}) {
   return emit('content_rating', payload);
 }
 
-export { contentRatingHash, NIBGATE_CONTENT_HASH_NAMESPACE, NIBGATE_REPUTATION_ABI, rateContentOnchain, reviewTextHash } from './reputation.js';
+export { contentRatingHash, NIBGATE_CONTENT_HASH_NAMESPACE, NIBGATE_REPUTATION_ABI, NIBGATE_REPUTATION_CHAIN_ID, NIBGATE_REPUTATION_CHAIN_NAME, NIBGATE_REPUTATION_CONTRACT, NIBGATE_REPUTATION_RPC_URL, rateContentOnchain, reviewTextHash } from './reputation.js';
 
 export function trackResourcePage(resource, options = {}) {
   const item = createGate(resource, options.gateOptions || {});

package/src/browser/reputation.js

@@ -6,6 +6,10 @@ const RATE_CONTENT_SELECTOR = '0xc62fad09';
 const ZERO_HASH = `0x${'0'.repeat(64)}`;
 
 export const NIBGATE_CONTENT_HASH_NAMESPACE = 'nibgate:content:v1';
+export const NIBGATE_REPUTATION_CHAIN_ID = 5042002;
+export const NIBGATE_REPUTATION_CHAIN_NAME = 'Arc Testnet';
+export const NIBGATE_REPUTATION_RPC_URL = 'https://rpc.testnet.arc.network';
+export const NIBGATE_REPUTATION_CONTRACT = '0x9f27fd62e75f86a3c7addfdba443aab1f930e281';
 
 export const NIBGATE_REPUTATION_ABI = [
   {
@@ -105,7 +109,7 @@ export async function rateContentOnchain(resource, options = {}) {
   const provider = options.provider || globalThis?.ethereum;
   if (!provider?.request) throw new Error('Connect an EVM wallet to rate this content onchain.');
 
-  const contractAddress = options.contractAddress || options.reputationContract;
+  const contractAddress = options.contractAddress || options.reputationContract || NIBGATE_REPUTATION_CONTRACT;
   if (!contractAddress) throw new Error('Nibgate reputation contract address is not configured.');
 
   const accounts = await provider.request({ method: 'eth_requestAccounts' });

package/src/index.d.ts

@@ -411,6 +411,10 @@ export declare function setupResourcePage(resource: NibgateResource | string, op
 export declare function rateResource(resource: NibgateResource | string, rating?: NibgateRating | number, extra?: Record<string, unknown>): boolean;
 export declare const NIBGATE_REPUTATION_ABI: readonly unknown[];
 export declare const NIBGATE_CONTENT_HASH_NAMESPACE: 'nibgate:content:v1';
+export declare const NIBGATE_REPUTATION_CHAIN_ID: 5042002;
+export declare const NIBGATE_REPUTATION_CHAIN_NAME: 'Arc Testnet';
+export declare const NIBGATE_REPUTATION_RPC_URL: 'https://rpc.testnet.arc.network';
+export declare const NIBGATE_REPUTATION_CONTRACT: '0x9f27fd62e75f86a3c7addfdba443aab1f930e281';
 export declare function contentRatingHash(resource: NibgateResource | string, options?: Record<string, unknown>): string;
 export declare function reviewTextHash(review?: string): string;
 export declare function rateContentOnchain(resource: NibgateResource | string, options: NibgateOnchainRatingOptions): Promise<NibgateOnchainRatingResult>;