@nibgate/sdk 0.1.0

package/src/browser/json.js

@@ -0,0 +1,8 @@
+export function jsonReplacer(_key, value) {
+  if (typeof value === 'bigint') return value.toString();
+  return value;
+}
+
+export function stringifyJson(value) {
+  return JSON.stringify(value, jsonReplacer);
+}

package/src/browser/reputation.js

@@ -0,0 +1,161 @@
+import { normalizeRating } from '../core/rating.js';
+import { normalizeResource } from '../core/resource.js';
+import { emit, payloadWithResource } from './events.js';
+
+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_ABI = [
+  {
+    type: 'function',
+    name: 'rateContent',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'contentId', type: 'bytes32' },
+      { name: 'rating', type: 'uint8' },
+      { name: 'reviewHash', type: 'bytes32' },
+      { name: 'unlockRef', type: 'string' }
+    ],
+    outputs: []
+  }
+];
+
+function stripHex(value = '') {
+  return String(value || '').replace(/^0x/i, '').toLowerCase();
+}
+
+function word(hex = '') {
+  const clean = stripHex(hex);
+  if (clean.length > 64) throw new Error('ABI word is too long.');
+  return clean.padStart(64, '0');
+}
+
+function wordRight(hex = '') {
+  const clean = stripHex(hex);
+  if (clean.length > 64) throw new Error('ABI word is too long.');
+  return clean.padEnd(64, '0');
+}
+
+function numberWord(value = 0) {
+  return Number(value || 0).toString(16).padStart(64, '0');
+}
+
+function utf8Hex(value = '') {
+  return Array.from(new TextEncoder().encode(String(value || '')))
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+function encodeString(value = '') {
+  const hex = utf8Hex(value);
+  const byteLength = hex.length / 2;
+  const paddedLength = Math.ceil(byteLength / 32) * 64;
+  return numberWord(byteLength) + hex.padEnd(paddedLength, '0');
+}
+
+function encodeRateContent({ contentId, ratingValue, reviewHash, unlockRef }) {
+  return RATE_CONTENT_SELECTOR
+    + wordRight(contentId)
+    + numberWord(ratingValue)
+    + wordRight(reviewHash || ZERO_HASH)
+    + numberWord(128)
+    + encodeString(unlockRef || '');
+}
+
+export function contentRatingHash(_resource, options = {}) {
+  const contentId = options.contentId || options.contentHash;
+  if (!contentId) {
+    throw new Error('contentId/contentHash is required. Use the Nibgate backend prepare endpoint or pass a known content hash.');
+  }
+  return contentId;
+}
+
+export function reviewTextHash(review = '') {
+  if (!review) return ZERO_HASH;
+  throw new Error('Text review hashing is not available in direct-browser mode. Pass reviewHash from your app/backend.');
+}
+
+async function prepareOnchainRating(resource, options = {}) {
+  if (options.contentId || options.contentHash) return { contentId: options.contentId || options.contentHash };
+  const prepareUrl = options.prepareUrl || options.indexUrl?.replace(/\/index$/, '/prepare');
+  if (!prepareUrl) throw new Error('contentId/contentHash or prepareUrl is required for onchain rating.');
+  const response = await fetch(prepareUrl, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...(options.indexHeaders || {}) },
+    body: JSON.stringify({
+      siteId: options.siteId,
+      token: options.token,
+      resource,
+      url: resource.url,
+      path: resource.path
+    })
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok || !payload.contentHash) throw new Error(payload.error || 'Could not prepare Nibgate onchain rating.');
+  return payload;
+}
+
+export async function rateContentOnchain(resource, options = {}) {
+  const normalized = normalizeResource(resource);
+  const rating = normalizeRating(options.rating ?? options.stars ?? options);
+  if (!rating.ratingValue) throw new Error('Rating must be between 0.1 and 5 stars.');
+
+  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;
+  if (!contractAddress) throw new Error('Nibgate reputation contract address is not configured.');
+
+  const accounts = await provider.request({ method: 'eth_requestAccounts' });
+  const walletAddress = Array.isArray(accounts) ? accounts[0] || '' : '';
+  if (!walletAddress) throw new Error('No wallet account selected.');
+
+  const prepared = await prepareOnchainRating(normalized, options);
+  const contentId = prepared.contentHash || prepared.contentId || contentRatingHash(normalized, options);
+  const reviewHash = options.reviewHash || ZERO_HASH;
+  const unlockRef = String(options.unlockRef || options.paymentId || options.txHash || '');
+  const data = encodeRateContent({ contentId, ratingValue: rating.ratingValue, reviewHash, unlockRef });
+
+  const txHash = await provider.request({
+    method: 'eth_sendTransaction',
+    params: [{
+      from: walletAddress,
+      to: contractAddress,
+      data
+    }]
+  });
+
+  const payload = payloadWithResource(normalized, {
+    rating: rating.rating,
+    ratingValue: rating.ratingValue,
+    walletAddress,
+    txHash,
+    contentHash: contentId,
+    reviewHash,
+    proofType: 'onchain_pending',
+    proof: unlockRef,
+    paymentId: options.paymentId,
+    actor: options.actor || 'human'
+  });
+  emit('content_rating', payload);
+
+  if (options.indexUrl) {
+    await fetch(options.indexUrl, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...(options.indexHeaders || {}) },
+      body: JSON.stringify({
+        siteId: options.siteId,
+        token: options.token,
+        txHash,
+        resource: normalized,
+        url: normalized.url,
+        path: normalized.path,
+        actor: options.actor || 'human'
+      })
+    }).catch(() => null);
+  }
+
+  return { txHash, walletAddress, contentId, ratingValue: rating.ratingValue, reviewHash };
+}

package/src/browser/storage.js

@@ -0,0 +1,68 @@
+import { browserWindow } from './env.js';
+import { normalizeResource } from '../core/resource.js';
+
+export function unlockStorageKey(resource) {
+  return `nibgate:unlock:${resource.id || resource.path || resource.url || 'content'}`;
+}
+
+export function proofStorageKey(resource) {
+  return `nibgate:payment-proof:${resource.id || resource.path || resource.url || 'content'}`;
+}
+
+export function markUnlocked(resource, payment = {}) {
+  const win = browserWindow();
+  if (!win) return false;
+  try {
+    win.localStorage.setItem(unlockStorageKey(resource), JSON.stringify({
+      unlockedAt: new Date().toISOString(),
+      payment
+    }));
+    return true;
+  } catch (_error) {
+    return false;
+  }
+}
+
+export function storePaymentProof(resource, proof) {
+  const win = browserWindow();
+  if (!win || !proof) return false;
+  try {
+    win.localStorage.setItem(proofStorageKey(resource), String(proof));
+    return true;
+  } catch (_error) {
+    return false;
+  }
+}
+
+export function getPaymentProof(resource) {
+  const win = browserWindow();
+  if (!win) return '';
+  try {
+    return win.localStorage.getItem(proofStorageKey(resource)) || '';
+  } catch (_error) {
+    return '';
+  }
+}
+
+export function clearPaymentProof(resource) {
+  const normalized = normalizeResource(resource);
+  const win = browserWindow();
+  if (!win) return false;
+  try {
+    win.localStorage.removeItem(proofStorageKey(normalized));
+    win.localStorage.removeItem(unlockStorageKey(normalized));
+    return true;
+  } catch (_error) {
+    return false;
+  }
+}
+
+export function hasUnlock(resource) {
+  const win = browserWindow();
+  if (!win) return false;
+  try {
+    return Boolean(win.localStorage.getItem(unlockStorageKey(resource)));
+  } catch (_error) {
+    return false;
+  }
+}

package/src/browser/tracking.js

@@ -0,0 +1,42 @@
+import { normalizeResource, validateResourceMetadata } from '../core/resource.js';
+import { browserWindow } from './env.js';
+import { emit, payloadWithResource } from './events.js';
+
+export function createTrackingGate(resource) {
+  const normalized = normalizeResource(resource);
+  return {
+    resource: normalized,
+    content(extra = {}) {
+      return emit('content_registered', payloadWithResource(normalized, extra));
+    },
+    view(extra = {}) {
+      return emit('resource_view', payloadWithResource(normalized, extra));
+    },
+    track(eventName, payload = {}) {
+      return emit(eventName, payloadWithResource(normalized, payload));
+    }
+  };
+}
+
+export function trackResourcePage(resource, options = {}) {
+  const item = createTrackingGate(resource);
+  const validation = validateResourceMetadata(item.resource, options.validation || {});
+  if ((validation.warnings.length || validation.errors.length) && options.warn !== false && browserWindow()?.console?.warn) {
+    browserWindow().console.warn('Nibgate content metadata needs attention', validation);
+  }
+
+  item.content({
+    source: options.source,
+    metadataQuality: { score: validation.score, warnings: validation.warnings, errors: validation.errors },
+    ...(options.content || {})
+  });
+  item.view({
+    source: options.source,
+    path: options.path || browserWindow()?.location?.pathname || item.resource.path,
+    referrer: options.referrer ?? browserWindow()?.document?.referrer ?? '',
+    ...(options.view || {})
+  });
+  return item;
+}
+
+export { normalizeResource, validateResourceMetadata };

package/src/browser/transfer.js

@@ -0,0 +1,53 @@
+import { normalizeResource } from '../core/resource.js';
+import { checkResourceAccess } from './index.js';
+
+export function createTransferCheckout(resource, options = {}) {
+  const normalized = normalizeResource({ ...resource, paymentRail: 'transfer' });
+  const sendTransfer = options.sendTransfer || options.transfer;
+  if (typeof sendTransfer !== 'function') {
+    throw new Error('createTransferCheckout requires sendTransfer({ resource, recipient, amount, currency, network }) and a server verifyTransfer hook.');
+  }
+
+  return {
+    resource: normalized,
+    async pay(input = {}) {
+      const recipient = normalized.recipient || normalized.payTo;
+      const amount = String(normalized.price || normalized.amount || '0');
+      const currency = normalized.currency || 'USDC';
+      const network = options.network || input.challenge?.accepts?.[0]?.network || 'eip155:5042002';
+      const result = await sendTransfer({ resource: normalized, recipient, amount, currency, network, challenge: input.challenge });
+      const txHash = result?.txHash || result?.hash || result?.transactionHash || result?.paymentId || '';
+      if (!txHash) throw new Error('Transfer checkout did not return a txHash.');
+      return {
+        paymentSignature: txHash,
+        signature: txHash,
+        memo: result.memo || '',
+        metadata: {
+          paymentProvider: 'direct-transfer',
+          paymentId: txHash,
+          txHash,
+          recipient,
+          amount: Number(amount),
+          currency,
+          network,
+          ...(result.metadata || result)
+        }
+      };
+    }
+  };
+}
+
+export async function payWithTransfer(resource, options = {}) {
+  const checkout = options.checkout || createTransferCheckout(resource, options).pay;
+  const result = await checkout({ resource: normalizeResource(resource), challenge: options.challenge || null });
+  const txHash = result?.metadata?.txHash || result?.txHash || result?.paymentSignature || result?.signature || '';
+  if (!txHash) throw new Error('Transfer checkout did not return a txHash.');
+  return checkResourceAccess(resource, {
+    ...options,
+    headers: {
+      ...(options.headers || {}),
+      'x-nibgate-transfer-tx': txHash
+    },
+    payment: result.metadata || { paymentProvider: 'direct-transfer', txHash, paymentId: txHash }
+  });
+}

package/src/core/payment.js

@@ -0,0 +1,8 @@
+export const PAYMENT_RAILS = ['gateway', 'transfer'];
+
+export function normalizePaymentRail(value, fallback = 'gateway') {
+  const rail = String(value || '').trim().toLowerCase().replace(/[-\s]+/g, '_');
+  if (rail === 'circle_gateway' || rail === 'x402') return 'gateway';
+  if (rail === 'direct_transfer' || rail === 'wallet_transfer') return 'transfer';
+  return PAYMENT_RAILS.includes(rail) ? rail : fallback;
+}

package/src/core/rating.js

@@ -0,0 +1,28 @@
+import { normalizeResource } from './resource.js';
+
+export function normalizeRating(input = {}) {
+  const value = typeof input === 'number' ? input : (input.rating ?? input.stars ?? input.ratingValue ?? input.score);
+  const numeric = Number.parseFloat(value);
+  const ratingValue = Number.isFinite(numeric)
+    ? Math.max(1, Math.min(50, numeric <= 5 ? Math.round(numeric * 10) : Math.round(numeric)))
+    : null;
+  return {
+    ...input,
+    rating: ratingValue ? ratingValue / 10 : undefined,
+    ratingValue: ratingValue || undefined
+  };
+}
+
+export function ratingMessage(resource, rating = {}, options = {}) {
+  const normalized = normalizeResource(resource);
+  const normalizedRating = normalizeRating(rating);
+  const value = normalizedRating.ratingValue || 0;
+  return [
+    'Nibgate content rating',
+    `site:${options.siteDomain || options.domain || normalized.siteDomain || normalized.domain || ''}`,
+    `content:${normalized.externalId || normalized.id}`,
+    `url:${normalized.url || options.url || ''}`,
+    `rating:${value}`,
+    'I confirm this rating is tied to my unlock/payment proof.'
+  ].join('\n');
+}

package/src/core/resource.js

@@ -0,0 +1,143 @@
+import { normalizePaymentRail } from './payment.js';
+export const CONTENT_TYPES = ['music', 'video', 'article', 'image'];
+export const TYPE_ALIASES = {
+  audio: 'music',
+  song: 'music',
+  track: 'music',
+  album: 'music',
+  playlist: 'music',
+  photo: 'image',
+  picture: 'image',
+  illustration: 'image',
+  art: 'image',
+  movie: 'video',
+  clip: 'video'
+};
+export const ACCESS_MODES = ['free', 'paid', 'blocked'];
+export const UNLOCK_MODES = ['one_time', 'metered_stream', 'metered_read', 'time_pass', 'agent_quota'];
+
+export function normalizeContentType(value) {
+  const type = String(value || '').trim().toLowerCase();
+  if (CONTENT_TYPES.includes(type)) return type;
+  return TYPE_ALIASES[type] || 'article';
+}
+
+export function normalizeAccessMode(value, fallback = 'paid') {
+  const mode = String(value || '').trim().toLowerCase();
+  return ACCESS_MODES.includes(mode) ? mode : fallback;
+}
+
+export function normalizeAccessPolicy(value = {}) {
+  if (typeof value === 'string') {
+    const mode = normalizeAccessMode(value);
+    return { humans: mode, agents: mode };
+  }
+
+  return {
+    humans: normalizeAccessMode(value.humans || value.human || value.default, 'paid'),
+    agents: normalizeAccessMode(value.agents || value.agent || value.default, 'paid')
+  };
+}
+
+export function normalizeUnlockPolicy(value = {}) {
+  const input = typeof value === 'string' ? { mode: value } : (value || {});
+  const mode = String(input.mode || input.type || 'one_time').trim().toLowerCase().replace(/[-\s]+/g, '_');
+  return {
+    ...input,
+    mode: UNLOCK_MODES.includes(mode) ? mode : 'one_time'
+  };
+}
+
+export function normalizeResource(resource = {}) {
+  const input = typeof resource === 'string' ? { id: resource } : (resource || {});
+  const {
+    publisher,
+    publisherId,
+    publisherWallet,
+    publisherHandle,
+    publisherName,
+    publisherProfileUrl,
+    publisherOrigin,
+    publisherVerification,
+    authorHandle,
+    ...v1Input
+  } = input;
+
+  return {
+    ...v1Input,
+    id: String(input.id || input.contentId || input.slug || '').trim(),
+    title: String(input.title || input.name || '').trim(),
+    type: normalizeContentType(input.type || input.contentType),
+    price: input.price ?? input.amount ?? '',
+    paymentRail: normalizePaymentRail(input.paymentRail || input.paymentMode || input.rail),
+    recipient: input.recipient || input.receiver || input.receiverAddress || input.payTo || input.creatorWallet || undefined,
+    payTo: input.payTo || input.recipient || input.receiver || input.receiverAddress || input.creatorWallet || undefined,
+    path: input.path || input.route || undefined,
+    url: input.url || undefined,
+    imageUrl: input.imageUrl || input.image || undefined,
+    tags: input.tags || undefined,
+    access: normalizeAccessPolicy(input.access),
+    unlock: normalizeUnlockPolicy(input.unlock)
+  };
+}
+
+function hasValue(value) {
+  if (Array.isArray(value)) return value.length > 0;
+  return value !== undefined && value !== null && String(value).trim() !== '';
+}
+
+function isPaidResource(resource = {}) {
+  const access = normalizeAccessPolicy(resource.access);
+  return access.humans === 'paid' || access.agents === 'paid' || Number.parseFloat(resource.price || resource.amount || '0') > 0;
+}
+
+export function validateResourceMetadata(resource = {}, options = {}) {
+  const normalized = normalizeResource(resource);
+  const warnings = [];
+  const errors = [];
+  const required = options.required || ['id', 'title', 'url', 'type'];
+  const recommended = options.recommended || ['description', 'imageUrl', 'tags'];
+
+  for (const field of required) {
+    if (!hasValue(normalized[field])) errors.push(`Missing required content metadata: ${field}`);
+  }
+
+  for (const field of recommended) {
+    if (!hasValue(normalized[field])) warnings.push(`Missing recommended discovery metadata: ${field}`);
+  }
+
+  if (!CONTENT_TYPES.includes(normalized.type)) errors.push('Content type must be one of music, video, article, or image.');
+
+  if (normalized.url && !/^https?:\/\//i.test(String(normalized.url))) {
+    warnings.push('Use an absolute canonical url for stronger discovery identity.');
+  }
+
+  if (normalized.imageUrl && !/^https?:\/\//i.test(String(normalized.imageUrl))) {
+    warnings.push('Use an absolute imageUrl for thumbnails in Explore and agent discovery.');
+  }
+
+  if (isPaidResource(normalized)) {
+    if (!hasValue(normalized.price)) errors.push('Paid content requires price.');
+    if (!hasValue(normalized.recipient || normalized.payTo)) errors.push('Paid content requires recipient/payTo wallet.');
+  }
+
+  const score = Math.max(0, 100 - errors.length * 20 - warnings.length * 8);
+  return {
+    ok: errors.length === 0,
+    score,
+    errors,
+    warnings,
+    resource: normalized
+  };
+}
+
+export function normalizeServerResource(resource = {}) {
+  const normalized = normalizeResource(resource);
+  return {
+    ...normalized,
+    title: normalized.title || String((typeof resource === 'object' && (resource.name || resource.id)) || 'Untitled content').trim(),
+    price: normalized.price || '0',
+    path: normalized.path || '/',
+    currency: normalized.currency || 'USDC'
+  };
+}

package/src/core/settings.js

@@ -0,0 +1,47 @@
+import { PAYMENT_RAILS, normalizePaymentRail } from './payment.js';
+import { ACCESS_MODES, CONTENT_TYPES, UNLOCK_MODES, normalizeAccessPolicy, normalizeContentType, normalizeUnlockPolicy } from './resource.js';
+
+export const NIBGATE_CONTENT_SETTING_FIELDS = [
+  { name: 'publishToNibgate', label: 'Publish to Nibgate discovery', type: 'boolean', defaultValue: true },
+  { name: 'type', label: 'Content type', type: 'select', options: CONTENT_TYPES, defaultValue: 'article' },
+  { name: 'humanAccess', label: 'Human access', type: 'select', options: ACCESS_MODES, defaultValue: 'paid' },
+  { name: 'agentAccess', label: 'Agent access', type: 'select', options: ACCESS_MODES, defaultValue: 'paid' },
+  { name: 'unlockMode', label: 'Unlock mode', type: 'select', options: UNLOCK_MODES, defaultValue: 'one_time' },
+  { name: 'paymentRail', label: 'Payment rail', type: 'select', options: PAYMENT_RAILS, defaultValue: 'gateway' },
+  { name: 'price', label: 'Price', type: 'text', defaultValue: '0.005' },
+  { name: 'currency', label: 'Currency', type: 'text', defaultValue: 'USDC' },
+  { name: 'recipient', label: 'Recipient wallet', type: 'wallet', defaultValue: '' },
+  { name: 'license', label: 'License / terms', type: 'textarea', defaultValue: '' }
+];
+
+export function createNibgateContentSettings(input = {}) {
+  const access = normalizeAccessPolicy(input.access || {
+    humans: input.humanAccess,
+    agents: input.agentAccess
+  });
+  const unlock = normalizeUnlockPolicy(input.unlock || input.unlockMode || 'one_time');
+
+  return {
+    publishToNibgate: input.publishToNibgate ?? input.publishedToNibgate ?? true,
+    type: normalizeContentType(input.type || input.contentType || 'article'),
+    humanAccess: access.humans,
+    agentAccess: access.agents,
+    unlockMode: unlock.mode,
+    paymentRail: normalizePaymentRail(input.paymentRail || input.paymentMode || input.rail),
+    price: String(input.price ?? input.amount ?? '0.005'),
+    currency: input.currency || 'USDC',
+    recipient: input.recipient || input.payTo || input.receiverAddress || input.creatorWallet || '',
+    license: input.license || input.terms || ''
+  };
+}
+
+export function settingsToAccessPolicy(settings = {}) {
+  return normalizeAccessPolicy({
+    humans: settings.humanAccess,
+    agents: settings.agentAccess
+  });
+}
+
+export function settingsToUnlockPolicy(settings = {}) {
+  return normalizeUnlockPolicy(settings.unlockMode || settings.unlock || 'one_time');
+}