Skip to content

api-reference.md

Latest commit

 

History

History
273 lines (192 loc) · 10.3 KB

api-reference.md

File metadata and controls

273 lines (192 loc) · 10.3 KB
Raw

API Reference

Import Paths

The SDK supports tree-shakeable subpath imports. You can import focused modules directly to minimize your bundle size:

  • @guildpass/sdk/client: Main GuildPassClient class.
  • @guildpass/sdk/errors: Error classes and codes (GuildPassError, GuildPassErrorCode).
  • @guildpass/sdk/utils: Utility functions (normaliseAddress, validateAddress, formatIsoDate, etc.).
  • @guildpass/sdk/types: TypeScript definitions.

You can also import everything from the root @guildpass/sdk.

GuildPassClient

The main constructor.

new GuildPassClient(config: GuildPassClientConfig)

Methods

  • getConfig(): Returns the current non-sensitive configuration. Sensitive values such as apiKey are omitted from this public snapshot.

Access Module (client.access)

checkAccess(params: AccessCheckParams, options?: RequestOptions)

Checks if a wallet can access a resource.

  • Returns: Promise<AccessCheckResult>

checkAccessBatch(items: AccessCheckParams[], options?: AccessCheckBatchOptions & RequestOptions)

Checks access for multiple resources or wallets concurrently.

  • Returns: Promise<AccessCheckBatchResult[]>

checkRoleAccess(params: RoleAccessCheckParams, options?: RequestOptions)

Checks if a wallet has a specific role.

  • Returns: Promise<boolean>

Membership Module (client.membership)

getMembership(params: MembershipParams, options?: RequestOptions)

Fetches detailed membership status.

  • Returns: Promise<Membership>

isMember(params: MembershipParams, options?: RequestOptions)

Quick check for active membership.

  • Returns: Promise<boolean>

Roles Module (client.roles)

getRoles(params: GetRolesParams, options?: RequestOptions)

Fetches all roles for a guild.

  • Returns: Promise<GuildRole[]>

getUserRoles(params: GetUserRolesParams, options?: RequestOptions)

Fetches roles assigned to a user.

  • Returns: Promise<GuildRole[]>

Guilds Module (client.guilds)

getGuild(params: GetGuildParams, options?: RequestOptions)

Fetches basic guild metadata.

  • Returns: Promise<Guild>

getGuildConfig(params: GetGuildParams, options?: RequestOptions)

Fetches full guild configuration.

  • Returns: Promise<GuildConfig>

Contract Module (client.contracts)

getGuildOwner(params: GuildOwnerParams)

Fetches the owner wallet address for a guild through the configured JSON-RPC provider and contract address.

await client.contracts.getGuildOwner({
  guildId: 'guild_1',
  chainId: 8453, // optional chain override
  contractAddress: '0x0000000000000000000000000000000000000000', // optional contract override
});
  • Returns: Promise<string>
  • Requires: an rpcUrl and a contract address from the resolved chain config or per-call contractAddress
  • Contract call: eth_call to getGuildOwner(bytes32)
  • Guild ID encoding: accepts a 32-byte hex value, unsigned integer string, or UTF-8 string up to 32 bytes
  • Errors: throws INVALID_CONFIG for missing RPC/contract config, INVALID_INPUT for invalid guild IDs, INVALID_ADDRESS for invalid contract addresses, HTTP_ERROR for RPC failures, and INVALID_RESPONSE for malformed RPC return data

getMembershipTokenBalance(params: TokenBalanceParams)

Fetches the raw membership token balance for a wallet through the configured JSON-RPC provider and contract address.

await client.contracts.getMembershipTokenBalance({
  walletAddress: '0x1234567890123456789012345678901234567890',
  chainId: 8453, // optional chain override
  contractAddress: '0x0000000000000000000000000000000000000000', // optional contract override
});
  • Returns: Promise<string>
  • Requires: rpcUrl and either contractAddress in client config or a per-call override
  • Contract call: eth_call to balanceOf(address)
  • Errors: throws INVALID_CONFIG for missing RPC/contract config, INVALID_ADDRESS for invalid wallet or contract addresses, HTTP_ERROR for RPC failures, and INVALID_RESPONSE for malformed RPC return data

getMembershipTokenBalancesBatch(params: TokenBalancesBatchParams)

Fetches membership token balances for multiple wallet addresses in a single JSON-RPC batch request. Preserves the input order of wallet addresses.

await client.contracts.getMembershipTokenBalancesBatch({
  walletAddresses: [
    '0x1234567890123456789012345678901234567890',
    '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
  ],
  chainId: 8453, // optional chain override
  contractAddress: '0x0000000000000000000000000000000000000000', // optional contract override
  maxBatchSize: 100, // optional limit to avoid provider payload limits (default 100)
  chunk: true, // optional automatic splitting
});
  • Returns: Promise<BatchItemResult[]> — ordered results, one per input address. Each result has { status: 'success', result: '<balance-as-string>' } or { status: 'error', error: '<reason>' }.
  • Requires: same config as getMembershipTokenBalance
  • Contract call: single JSON-RPC batch of eth_call to balanceOf(address)
  • Partial failures: a failed address is reported individually; other addresses are unaffected
  • Errors: throws INVALID_INPUT for empty arrays, INVALID_ADDRESS if any address is invalid (pre-flight), INVALID_CONFIG for missing RPC/contract config, INVALID_RESPONSE for non-array or malformed batch responses

getGuildOwnersBatch(params: GuildOwnersBatchParams)

Fetches owners for multiple guild IDs in a single JSON-RPC batch request. Preserves the input order of guild IDs.

await client.contracts.getGuildOwnersBatch({
  guildIds: ['guild_1', 'guild_2', '42'],
  chainId: 8453, // optional chain override
  contractAddress: '0x0000000000000000000000000000000000000000', // optional contract override
  maxBatchSize: 100, // optional limit (default 100)
  chunk: true, // automatically split if guildIds exceeds maxBatchSize
});
  • Returns: Promise<BatchItemResult[]> — ordered results, one per input guild ID. Each result has { status: 'success', result: '<owner-address>' } or { status: 'error', error: '<reason>' }.
  • Requires: same config as getGuildOwner
  • Contract call: single JSON-RPC batch of eth_call to getGuildOwner(bytes32)
  • Partial failures: a failed guild is reported individually; other guilds are unaffected
  • Errors: throws INVALID_INPUT for empty arrays, INVALID_INPUT if any guild ID is invalid (pre-flight), INVALID_CONFIG for missing RPC/contract config, INVALID_RESPONSE for non-array or malformed batch responses

batchEthCall(calls: BatchEthCallItem[], rpcUrl: string, options?: RequestOptions & { maxBatchSize?: number, chunk?: boolean })

Low-level helper for sending multiple arbitrary eth_call requests in one JSON-RPC batch. Returns ordered per-item results. By default, it limits batches to 100 calls and throws an error if exceeded, unless chunk: true is passed.

const results = await client.contracts.batchEthCall(
  [
    { to: '0xContractA', data: '0x70a08231...' },
    { to: '0xContractB', data: '0xab4511dc...' },
  ],
  'https://rpc.example.com',
  { maxBatchSize: 50, chunk: true }
);
  • Returns: Promise<BatchItemResult[]> — ordered results, one per input call
  • Partial failures: each call is individually resolved; errors do not affect sibling calls
  • Input validation: each to address is validated as an Ethereum address before the RPC request is built
  • Errors: throws INVALID_INPUT for empty/ invalid call descriptors, INVALID_CONFIG for missing rpcUrl, INVALID_ADDRESS for malformed to addresses, HTTP_ERROR for HTTP or RPC-level failures, INVALID_RESPONSE for non-array or structurally malformed batch responses
  • Provider compatibility: works with any JSON-RPC provider that supports batch requests

Response Validation

By default, service methods trust that the API response matches the declared TypeScript return type. Since that's only a compile-time guarantee, a malformed or incompatible response from the API (or a misbehaving mock/proxy in front of it) would otherwise be returned to your code as-is.

Set validateResponses: true in the client config to opt into runtime checks on responses for the core public types (AccessCheckResult, Membership, GuildRole, Guild, GuildConfig):

const client = new GuildPassClient({
  apiUrl: '...',
  validateResponses: true,
});

When enabled, a response that doesn't match the expected shape causes the SDK method to throw a GuildPassError with code: GuildPassErrorCode.INVALID_RESPONSE, instead of silently returning malformed data:

try {
  await client.access.checkAccess({ ... });
} catch (error) {
  if (error instanceof GuildPassError && error.code === GuildPassErrorCode.INVALID_RESPONSE) {
    // The API returned a response that doesn't match AccessCheckResult.
  }
}

This flag defaults to false to preserve existing behaviour for current consumers. The guards themselves (isAccessCheckResult, isMembership, isGuildRoleArray, isGuild, isGuildConfig) are also exported directly from the package if you want to validate responses yourself without enabling the flag:

import { isGuild } from '@guildpass/sdk';

if (!isGuild(someUnknownValue)) {
  // handle the malformed payload
}

The guards are hand-written, dependency-free type predicates — no schema validation library is used, so enabling this option has a negligible effect on bundle size.

Contract Testing

The SDK maintains an API schema fixture to ensure request and response assumptions are valid. Contract tests (tests/services.test.ts) assert that SDK method parameters map to the correct API endpoint and match expected schema response structures.

When the API contract changes, you must update the fixture (tests/fixtures/api-contract.json) to reflect the new structure:

  1. Locate the endpoint within api-contract.json.
  2. Update the request.path or request.query array if parameters change.
  3. Update the response.success object to match the new successful response.
  4. Update the response.error object if error formats change.
  5. Run npm test to verify your SDK methods conform to the new API schema.