@meddleware/nft-gate-client 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.3] - 2026-08-29
+
+### Added
+
+- Gate administration PTB builders (AdminCap-gated): `buildSetPriceTx`, `buildSetPaymentRecipientTx`, `buildSetPausedTx`, `buildSetDefaultUsesTx`, `buildSetSoulboundTx`, `buildSetAutoBurnAtZeroTx`, `buildSetNftNameTx`, `buildSetNftImageUrlTx`, `buildSetNftDescriptionTx`, `buildAirdropTx`, `buildMakeGateImmutableTx`
+- `GateAdminContext` type (`{ packageId, gateId, adminCapId }`) for the management builders
+- Gate discovery helpers: `fetchOwnedGates`, `fetchAdminCaps`, `fetchGate`, `parseAdminCap`, `parseGate`, and the `OwnedGate` type — list and read the gates an operator administers
+- `@throws` annotations on the async ownership / challenge / proof functions
+
 ## [0.0.1] - 2026-08-27
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meddleware/nft-gate-client",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "description": "Client-side helpers for the access_gate NFT access primitive: ownership queries, purchase/consume PTB builders, challenge signing, and access-proof assembly.",
   "author": "MeddleWare <meddleware@proton.me>",
@@ -9,7 +9,13 @@
     "type": "git",
     "url": "git+https://github.com/meddleware-org/nft-gate-client.git"
   },
-  "keywords": ["sui", "nft", "access-control", "web3", "move"],
+  "keywords": [
+    "sui",
+    "nft",
+    "access-control",
+    "web3",
+    "move"
+  ],
   "files": [
     "src",
     "CHANGELOG.md"
@@ -33,4 +39,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/challenge.ts

@@ -3,6 +3,9 @@ import type { Challenge } from './types.js'
 /**
  * Fetch a fresh challenge from a gateway's `GET /v1/challenge` endpoint. Tolerates both
  * `expiresAt` (camelCase) and `expires_at` (snake_case) response shapes.
+ *
+ * @throws {Error} if the network request fails or the gateway returns a non-2xx status.
+ * @throws {Error} if the response body is missing the required `nonce` field.
  */
 export async function fetchChallenge(
   gatewayHost: string,

package/src/index.ts

@@ -7,6 +7,8 @@
 
 export type {
   AccessGateConfig,
+  GateAdminContext,
+  OwnedGate,
   Challenge,
   AccessProof,
   OwnedAccessNft,
@@ -14,8 +16,33 @@ export type {
   SuiObjectClient,
 } from './types.js'
 
-export { fetchAccessNfts, ownsAccessNft, parseOwnedAccessNft, fetchAccessNftById } from './ownership.js'
-export { buildPurchaseTx, buildConsumeTx, buildCreateGateTx } from './ptb.js'
+export {
+  fetchAccessNfts,
+  ownsAccessNft,
+  parseOwnedAccessNft,
+  fetchAccessNftById,
+  parseAdminCap,
+  parseGate,
+  fetchAdminCaps,
+  fetchGate,
+  fetchOwnedGates,
+} from './ownership.js'
+export {
+  buildPurchaseTx,
+  buildConsumeTx,
+  buildCreateGateTx,
+  buildSetPriceTx,
+  buildSetPaymentRecipientTx,
+  buildSetPausedTx,
+  buildSetDefaultUsesTx,
+  buildSetSoulboundTx,
+  buildSetAutoBurnAtZeroTx,
+  buildSetNftNameTx,
+  buildSetNftImageUrlTx,
+  buildSetNftDescriptionTx,
+  buildAirdropTx,
+  buildMakeGateImmutableTx,
+} from './ptb.js'
 export { fetchChallenge } from './challenge.js'
 export {
   personalMessageForNonce,

package/src/ownership.ts

@@ -1,4 +1,4 @@
-import type { OwnedAccessNft, OwnedObjectsClient, SuiObjectClient } from './types.js'
+import type { OwnedAccessNft, OwnedGate, OwnedObjectsClient, SuiObjectClient } from './types.js'
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
@@ -50,6 +50,8 @@ export function parseOwnedAccessNft(entry: any): OwnedAccessNft | null {
  * Typed single-object read of one access NFT by id (`getObject` with `showType`+`showContent`),
  * used when a UI needs the **exact** `usesRemaining` reliably rather than the best-effort parse
  * of an owned-objects page. Returns `null` if the object is missing or not an access NFT.
+ *
+ * @throws {Error} if the RPC call fails at the network or transport layer.
  */
 export async function fetchAccessNftById(
   client: SuiObjectClient,
@@ -65,6 +67,8 @@ export async function fetchAccessNftById(
 /**
  * Fetch all access NFTs of `nftType` owned by `owner`, optionally restricted to a specific
  * `gateId`. Uses `getOwnedObjects` filtered by `StructType` (the standard owned-objects query).
+ *
+ * @throws {Error} if the RPC call fails at the network or transport layer.
  */
 export async function fetchAccessNfts(
   client: OwnedObjectsClient,
@@ -87,6 +91,8 @@ export async function fetchAccessNfts(
  * True if `owner` holds at least one access NFT of `nftType` (optionally for `gateId`).
  * This is the cheap check a frontend runs to decide whether to show a gated option, and a
  * gateway runs (server-side) as part of access verification.
+ *
+ * @throws {Error} if the underlying RPC call fails.
  */
 export async function ownsAccessNft(
   client: OwnedObjectsClient,
@@ -97,3 +103,108 @@ export async function ownsAccessNft(
   const nfts = await fetchAccessNfts(client, owner, nftType, gateId)
   return nfts.length > 0
 }
+
+// ── Gate discovery (operator management) ─────────────────────────────────────────
+// An operator holds an `AdminCap` per gate they administer. Discovery: list owned AdminCaps
+// (filtered by StructType), read each cap's `gate_id`, then fetch the shared `Gate` object.
+
+/** True if `type` names the `access_gate::AdminCap` struct. */
+function isAdminCapType(type: unknown): boolean {
+  return typeof type === 'string' && /::access_gate::AdminCap\b/.test(type)
+}
+
+/**
+ * Parse a single `getOwnedObjects`/`getObject` entry into `{ adminCapId, gateId }`, or `null` if
+ * it is not an `AdminCap`. Validates the object **type** when present and reads `fields.gate_id`.
+ */
+export function parseAdminCap(entry: any): { adminCapId: string; gateId: string } | null {
+  const obj = entry?.data ?? entry
+  const adminCapId: string | undefined = obj?.objectId ?? obj?.content?.fields?.id?.id
+  const type: unknown = obj?.type ?? obj?.content?.type
+  if (type !== undefined && !isAdminCapType(type)) return null
+  const gateId: string | undefined = obj?.content?.fields?.gate_id ?? obj?.content?.fields?.gateId
+  if (!adminCapId || !gateId) return null
+  return { adminCapId, gateId }
+}
+
+/**
+ * Parse a `getObject` entry for a `Gate` shared object into an {@link OwnedGate} (minus
+ * `adminCapId`, which comes from the owning cap). Returns `null` if the object is missing its
+ * expected `Gate` fields.
+ */
+export function parseGate(entry: any): Omit<OwnedGate, 'adminCapId'> | null {
+  const obj = entry?.data ?? entry
+  const gateId: string | undefined = obj?.objectId ?? obj?.content?.fields?.id?.id
+  const f = obj?.content?.fields
+  if (!gateId || !f) return null
+  return {
+    gateId,
+    priceMist: BigInt(f.price_mist ?? 0),
+    paymentRecipient: String(f.payment_recipient ?? ''),
+    defaultUses: BigInt(f.default_uses ?? 0),
+    soulbound: Boolean(f.soulbound),
+    autoBurnAtZero: Boolean(f.auto_burn_at_zero),
+    paused: Boolean(f.paused),
+    frozen: Boolean(f.frozen),
+    nftName: String(f.nft_name ?? ''),
+    nftImageUrl: String(f.nft_image_url ?? ''),
+    nftDescription: String(f.nft_description ?? ''),
+  }
+}
+
+/**
+ * List the `{ adminCapId, gateId }` pairs for every `access_gate::AdminCap` owned by `owner`
+ * under `packageId`. Uses `getOwnedObjects` filtered by `StructType` (the standard query).
+ *
+ * @throws {Error} if the underlying RPC call fails.
+ */
+export async function fetchAdminCaps(
+  client: OwnedObjectsClient,
+  owner: string,
+  packageId: string,
+): Promise<{ adminCapId: string; gateId: string }[]> {
+  const { data } = await client.getOwnedObjects({
+    owner,
+    filter: { StructType: `${packageId}::access_gate::AdminCap` },
+    options: { showContent: true, showType: true },
+  })
+  return (data ?? [])
+    .map(parseAdminCap)
+    .filter((c): c is { adminCapId: string; gateId: string } => c !== null)
+}
+
+/**
+ * Typed single-object read of one `Gate` by id, returning its parsed state (without `adminCapId`).
+ * Returns `null` if the object is missing or not a `Gate`.
+ *
+ * @throws {Error} if the RPC call fails at the network or transport layer.
+ */
+export async function fetchGate(
+  client: SuiObjectClient,
+  gateId: string,
+): Promise<Omit<OwnedGate, 'adminCapId'> | null> {
+  const res = await client.getObject({ id: gateId, options: { showType: true, showContent: true } })
+  return parseGate(res)
+}
+
+/**
+ * Fetch every gate `owner` administers: list their owned `AdminCap`s, then fetch each referenced
+ * `Gate` shared object and merge in the owning `adminCapId`. Gates whose object can no longer be
+ * read (e.g. deleted) are skipped.
+ *
+ * @throws {Error} if an underlying RPC call fails at the network or transport layer.
+ */
+export async function fetchOwnedGates(
+  client: OwnedObjectsClient & SuiObjectClient,
+  owner: string,
+  packageId: string,
+): Promise<OwnedGate[]> {
+  const caps = await fetchAdminCaps(client, owner, packageId)
+  const gates = await Promise.all(
+    caps.map(async ({ adminCapId, gateId }) => {
+      const gate = await fetchGate(client, gateId)
+      return gate ? { ...gate, adminCapId } : null
+    }),
+  )
+  return gates.filter((g): g is OwnedGate => g !== null)
+}

package/src/proof.ts

@@ -38,6 +38,8 @@ export type PersonalMessageSigner = (message: Uint8Array) => Promise<{ signature
 /**
  * Sign a challenge and assemble the encoded access-proof token to hand to any gateway as its
  * auth bearer (e.g. an upload-relay client's auth-token option, an `Authorization` header).
+ *
+ * @throws {Error} if the wallet signer rejects or fails to sign the message.
  */
 export async function buildAccessProof(opts: {
   address: string

package/src/ptb.ts

@@ -1,5 +1,5 @@
 import { Transaction } from '@mysten/sui/transactions'
-import type { AccessGateConfig } from './types.js'
+import type { AccessGateConfig, GateAdminContext } from './types.js'
 
 /**
  * Build a PTB that purchases access: split `priceMist` from the gas coin and call
@@ -69,3 +69,91 @@ export function buildCreateGateTx(
   })
   return tx
 }
+
+// ── Gate administration (AdminCap-gated) ─────────────────────────────────────────
+// Builders for the operator management surface. Each calls an `assert_admin`-gated entry
+// point with `[adminCap, gate, <value>]`; the operator signs + executes with their wallet.
+// The on-chain call aborts (`E_WRONG_GATE` / `E_FROZEN`) if the cap/gate mismatch or the
+// gate is frozen, so these never need to pre-check.
+
+/** The element type accepted by a `moveCall`'s `arguments` array. */
+type MoveCallArg = NonNullable<Parameters<Transaction['moveCall']>[0]['arguments']>[number]
+
+/** Build a single-`moveCall` admin PTB: `<fn>(adminCap, gate, ...extraArgs)`. */
+function buildGateAdminCall(
+  ctx: GateAdminContext,
+  fn: string,
+  extraArgs: (tx: Transaction) => MoveCallArg[],
+): Transaction {
+  const tx = new Transaction()
+  tx.moveCall({
+    target: `${ctx.packageId}::access_gate::${fn}`,
+    arguments: [tx.object(ctx.adminCapId), tx.object(ctx.gateId), ...extraArgs(tx)],
+  })
+  return tx
+}
+
+/** Set the gate price (in MIST) charged by future `purchase` calls (0 = free). */
+export function buildSetPriceTx(ctx: GateAdminContext, priceMist: bigint | number): Transaction {
+  return buildGateAdminCall(ctx, 'set_price', (tx) => [tx.pure.u64(priceMist)])
+}
+
+/** Redirect future purchase payments to a new recipient address. */
+export function buildSetPaymentRecipientTx(ctx: GateAdminContext, recipient: string): Transaction {
+  return buildGateAdminCall(ctx, 'set_payment_recipient', (tx) => [tx.pure.address(recipient)])
+}
+
+/** Pause or unpause `purchase` (paused ⇒ `purchase` aborts with `E_PAUSED`). */
+export function buildSetPausedTx(ctx: GateAdminContext, paused: boolean): Transaction {
+  return buildGateAdminCall(ctx, 'set_paused', (tx) => [tx.pure.bool(paused)])
+}
+
+/** Change the default uses for future mints (0 ⇒ unlimited pass; N ⇒ single-use with N). */
+export function buildSetDefaultUsesTx(ctx: GateAdminContext, defaultUses: bigint | number): Transaction {
+  return buildGateAdminCall(ctx, 'set_default_uses', (tx) => [tx.pure.u64(defaultUses)])
+}
+
+/** Switch the soulbound flag for future mints (does not affect already-minted NFTs). */
+export function buildSetSoulboundTx(ctx: GateAdminContext, soulbound: boolean): Transaction {
+  return buildGateAdminCall(ctx, 'set_soulbound', (tx) => [tx.pure.bool(soulbound)])
+}
+
+/** Toggle the auto-burn-at-zero policy for future mints. */
+export function buildSetAutoBurnAtZeroTx(ctx: GateAdminContext, autoBurn: boolean): Transaction {
+  return buildGateAdminCall(ctx, 'set_auto_burn_at_zero', (tx) => [tx.pure.bool(autoBurn)])
+}
+
+/** Update the default NFT display name for future mints. */
+export function buildSetNftNameTx(ctx: GateAdminContext, name: string): Transaction {
+  return buildGateAdminCall(ctx, 'set_nft_name', (tx) => [tx.pure.string(name)])
+}
+
+/** Update the default NFT image URL for future mints. */
+export function buildSetNftImageUrlTx(ctx: GateAdminContext, url: string): Transaction {
+  return buildGateAdminCall(ctx, 'set_nft_image_url', (tx) => [tx.pure.string(url)])
+}
+
+/** Update the default NFT description for future mints. */
+export function buildSetNftDescriptionTx(ctx: GateAdminContext, description: string): Transaction {
+  return buildGateAdminCall(ctx, 'set_nft_description', (tx) => [tx.pure.string(description)])
+}
+
+/** AdminCap-gated free grant (airdrop) of the gate's NFT flavour to `recipient`. */
+export function buildAirdropTx(ctx: GateAdminContext, recipient: string): Transaction {
+  return buildGateAdminCall(ctx, 'airdrop', (tx) => [tx.pure.address(recipient)])
+}
+
+/**
+ * Make the gate immutable — **irreversible**. Consumes the `AdminCap` (passed by value) and sets
+ * `Gate.frozen = true`, permanently ending all setters and `airdrop`. `purchase`/`consume` remain
+ * permissionless. Grant everything first, then freeze.
+ */
+export function buildMakeGateImmutableTx(ctx: GateAdminContext): Transaction {
+  const tx = new Transaction()
+  tx.moveCall({
+    target: `${ctx.packageId}::access_gate::make_gate_immutable`,
+    // cap is consumed by value; gate is &mut.
+    arguments: [tx.object(ctx.adminCapId), tx.object(ctx.gateId)],
+  })
+  return tx
+}

package/src/types.ts

@@ -23,6 +23,48 @@ export interface AccessGateConfig {
   soulbound?: boolean
 }
 
+/**
+ * Identifies a gate an operator administers, for the AdminCap-gated management PTB builders
+ * (setters, airdrop, freeze). The three ids together authorise a call: `adminCapId` must be the
+ * `AdminCap` whose `gate_id` matches `gateId`, under the published `packageId`.
+ */
+export interface GateAdminContext {
+  /** Published `access_gate` package ID. */
+  packageId: string
+  /** The shared `Gate` object ID being administered. */
+  gateId: string
+  /** The `AdminCap` object ID authorised over `gateId` (held by the operator). */
+  adminCapId: string
+}
+
+/** A gate an operator administers, parsed from its on-chain `Gate` object + owning `AdminCap`. */
+export interface OwnedGate {
+  /** The shared `Gate` object ID. */
+  gateId: string
+  /** The `AdminCap` object ID that authorises administering this gate. */
+  adminCapId: string
+  /** Price in MIST charged by `purchase` (0 = free). */
+  priceMist: bigint
+  /** Address that receives the operator share of each paid `purchase`. */
+  paymentRecipient: string
+  /** 0 ⇒ unlimited passes; N ⇒ single-use NFTs with N uses. */
+  defaultUses: bigint
+  /** Whether newly-minted NFTs are soulbound. */
+  soulbound: boolean
+  /** Whether a single-use NFT is deleted (vs. kept as a receipt) at zero uses. */
+  autoBurnAtZero: boolean
+  /** Whether `purchase` is currently disabled. */
+  paused: boolean
+  /** Whether the gate has been made immutable (all admin/airdrop permanently disabled). */
+  frozen: boolean
+  /** Default NFT display name minted into future NFTs. */
+  nftName: string
+  /** Default NFT image URL minted into future NFTs. */
+  nftImageUrl: string
+  /** Default NFT description minted into future NFTs. */
+  nftDescription: string
+}
+
 /** A server-issued, time-bound challenge the wallet signs to prove control of an address. */
 export interface Challenge {
   /** Opaque nonce (as issued by the gateway; treated as a UTF-8 string end-to-end). */