discolisting 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# discolisting
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official TypeScript SDK for the [DiscoListing](https://discolisting.com) public API. Zero dependencies; works in Node 18+, Bun,
+Deno and edge runtimes (uses `fetch` and Web Crypto).
+
+```sh
+npm install discolisting
+```
+
+## Quick start
+
+```ts
+import { ListingClient, verifyWebhook } from 'discolisting'
+
+const client = new ListingClient({
+  apiKey: process.env.LISTING_API_KEY, // from your listing's Integrations page
+})
+
+// Bots: post your server count now and every 30 minutes
+const stop = client.autoPost(() => ({ serverCount: bot.guilds.cache.size }), {
+  onError: console.error,
+})
+
+// Reward voters (24 h cooldown for servers, 12 h for bots)
+const { voted, nextVoteAt } = await client.hasVoted(interaction.user.id)
+
+// Recent votes, newest first
+const votes = await client.getVotes({ limit: 50 })
+
+// Public lookups (no key needed)
+const server = await client.getServer('my-server-slug')
+const someBot = await client.getBot('123456789012345678')
+
+// Embed a live widget in a README
+const img = client.widgetUrl('server', 'my-server-slug', { style: 'badge', stats: ['members'] })
+```
+
+## Vote webhooks
+
+Each vote is POSTed to your endpoint, signed with `X-Listing-Signature: t=<unix>,v1=<hmac>`.
+Verify it against the **raw** request body (not re-serialised JSON):
+
+```ts
+import { parseWebhook } from 'discolisting'
+
+app.post('/listing-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
+  const event = await parseWebhook(
+    req.body.toString('utf8'),
+    req.header('x-listing-signature'),
+    process.env.WEBHOOK_SECRET!,
+  )
+  if (!event) return res.sendStatus(401)
+  if (event.event === 'vote') await rewardUser(event.data.userId)
+  res.sendStatus(204)
+})
+```
+
+Signatures older than five minutes are rejected to stop replays (`toleranceSeconds` to change).
+
+## Testing against another site
+
+The client talks to `https://discolisting.com/api/v1` by default. Point it elsewhere (a local dev server or
+a staging tunnel) with `baseUrl`:
+
+```ts
+new ListingClient({ apiKey, baseUrl: 'http://localhost:3000/api/v1' })
+```
+
+## Errors
+
+Failed requests throw `ListingApiError` with `status`, `message` and, for rate limits (429),
+`retryAfter` in seconds.
+
+## API
+
+| Method                                              | Needs key | Description                             |
+| --------------------------------------------------- | --------- | --------------------------------------- |
+| `getServer(id)`                                     | no        | Server by guild ID, listing ID or slug  |
+| `getBot(id)`                                        | no        | Bot by bot ID, listing ID or slug       |
+| `hasVoted(userId)`                                  | yes       | Vote status for a Discord user          |
+| `getVotes({ limit, before })`                       | yes       | Recent votes, newest first              |
+| `postStats({ serverCount, shardCount?, shardId? })` | yes       | Report bot server count                 |
+| `autoPost(getStats, { intervalMs, onError })`       | yes       | Post stats on a timer; returns `stop()` |
+| `widgetUrl(kind, slug, options)`                    | no        | URL of the live SVG widget              |
+| `verifyWebhook(body, header, secret)`               | –         | Check a webhook signature               |
+| `parseWebhook(body, header, secret)`                | –         | Verify and parse a webhook              |

package/dist/index.cjs

@@ -0,0 +1,160 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/index.ts
+/**
+* Official TypeScript SDK for the DiscoListing public API (https://discolisting.com/api/v1).
+* Zero dependencies; works in Node 18+, Bun, Deno and edge runtimes (fetch + Web Crypto).
+*/
+const SDK_VERSION = "0.2.0";
+/** The public API. Override `baseUrl` only to test against a local or staging site. */
+const DEFAULT_BASE_URL = "https://discolisting.com/api/v1";
+var ListingApiError = class extends Error {
+	status;
+	retryAfter;
+	constructor(status, message, retryAfter = null) {
+		super(message);
+		this.status = status;
+		this.retryAfter = retryAfter;
+		this.name = "ListingApiError";
+	}
+};
+var ListingClient = class {
+	apiKey;
+	baseUrl;
+	fetchImpl;
+	timeoutMs;
+	constructor(opts = {}) {
+		this.apiKey = opts.apiKey;
+		this.baseUrl = (opts.baseUrl || "https://discolisting.com/api/v1").replace(/\/+$/, "");
+		this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+		this.timeoutMs = opts.timeoutMs ?? 1e4;
+	}
+	async request(method, path, opts = {}) {
+		const url = new URL(`${this.baseUrl}${path}`);
+		for (const [k, v] of Object.entries(opts.query ?? {})) if (v !== void 0) url.searchParams.set(k, String(v));
+		const headers = {
+			Accept: "application/json",
+			"User-Agent": `listing-sdk/${SDK_VERSION}`
+		};
+		if (opts.auth) {
+			if (!this.apiKey) throw new ListingApiError(401, "This method needs an apiKey");
+			headers.Authorization = `Bearer ${this.apiKey}`;
+		}
+		if (opts.body !== void 0) headers["Content-Type"] = "application/json";
+		const res = await this.fetchImpl(url, {
+			method,
+			headers,
+			body: opts.body === void 0 ? void 0 : JSON.stringify(opts.body),
+			signal: AbortSignal.timeout(this.timeoutMs)
+		});
+		const data = await res.json().catch(() => ({}));
+		if (!res.ok) {
+			const retry = res.headers.get("retry-after");
+			throw new ListingApiError(res.status, data.error ?? res.statusText, retry ? Number(retry) : null);
+		}
+		return data;
+	}
+	/** Look up a server by guild ID, listing ID or slug. */
+	getServer(id) {
+		return this.request("GET", `/servers/${encodeURIComponent(id)}`);
+	}
+	/** Look up a bot by bot ID, listing ID or slug. */
+	getBot(id) {
+		return this.request("GET", `/bots/${encodeURIComponent(id)}`);
+	}
+	/** Did this Discord user vote for your listing within its cooldown (24 h servers, 12 h bots)? */
+	async hasVoted(userId) {
+		return this.request("GET", "/votes/check", {
+			query: { userId },
+			auth: true
+		});
+	}
+	/** Recent votes, newest first. Pass the last `votedAt` as `before` to page. */
+	async getVotes(opts = {}) {
+		return (await this.request("GET", "/votes", {
+			query: opts,
+			auth: true
+		})).votes;
+	}
+	/**
+	* Live SVG widget for a listing, for websites and READMEs (no API key needed).
+	* Mirrors the options on the listing's Integrations → Embed widget page.
+	*/
+	widgetUrl(kind, slug, opts = {}) {
+		const site = this.baseUrl.replace(/\/api\/v1$/, "");
+		const q = new URLSearchParams();
+		if (opts.style) q.set("style", opts.style);
+		if (opts.theme) q.set("theme", opts.theme);
+		if (opts.accent) q.set("accent", opts.accent.replace("#", ""));
+		if (opts.stats?.length) q.set("stats", opts.stats.join(","));
+		const qs = q.toString();
+		return `${site}/widget/${kind}/${encodeURIComponent(slug)}.svg${qs ? `?${qs}` : ""}`;
+	}
+	/** Report your bot's server count (at most once a minute per shard). */
+	postStats(stats) {
+		return this.request("POST", "/stats", {
+			body: stats,
+			auth: true
+		});
+	}
+	/**
+	* Post stats now and then every `intervalMs` (default 30 minutes, minimum 1 minute).
+	* Returns a function that stops the timer. Errors go to `onError` and never throw.
+	*/
+	autoPost(getStats, opts = {}) {
+		const interval = Math.max(6e4, opts.intervalMs ?? 18e5);
+		const run = async () => {
+			try {
+				await this.postStats(await getStats());
+			} catch (err) {
+				opts.onError?.(err);
+			}
+		};
+		run();
+		const timer = setInterval(() => void run(), interval);
+		timer.unref?.();
+		return () => clearInterval(timer);
+	}
+};
+function toHex(buf) {
+	return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function constantTimeEqual(a, b) {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return diff === 0;
+}
+/**
+* Verify a vote webhook. Pass the raw request body (not re-serialised JSON), the
+* `X-Listing-Signature` header and your signing secret. Rejects signatures older than
+* `toleranceSeconds` (default 300) to stop replays.
+*/
+async function verifyWebhook(rawBody, signatureHeader, secret, opts = {}) {
+	if (!signatureHeader) return false;
+	const parts = Object.fromEntries(signatureHeader.split(",").map((kv) => {
+		const i = kv.indexOf("=");
+		return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()];
+	}));
+	const t = Number(parts.t);
+	if (!parts.v1 || !Number.isFinite(t)) return false;
+	const now = opts.now ?? Math.floor(Date.now() / 1e3);
+	if (Math.abs(now - t) > (opts.toleranceSeconds ?? 300)) return false;
+	const enc = new TextEncoder();
+	const key = await globalThis.crypto.subtle.importKey("raw", enc.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return constantTimeEqual(toHex(await globalThis.crypto.subtle.sign("HMAC", key, enc.encode(`${String(t)}.${rawBody}`))), parts.v1);
+}
+/** Verify and parse a webhook in one step; returns null when the signature is invalid. */
+async function parseWebhook(rawBody, signatureHeader, secret) {
+	if (!await verifyWebhook(rawBody, signatureHeader, secret)) return null;
+	return JSON.parse(rawBody);
+}
+//#endregion
+exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.ListingApiError = ListingApiError;
+exports.ListingClient = ListingClient;
+exports.SDK_VERSION = SDK_VERSION;
+exports.parseWebhook = parseWebhook;
+exports.verifyWebhook = verifyWebhook;

package/dist/index.d.cts

@@ -0,0 +1,148 @@
+//#region src/index.d.ts
+/**
+ * Official TypeScript SDK for the DiscoListing public API (https://discolisting.com/api/v1).
+ * Zero dependencies; works in Node 18+, Bun, Deno and edge runtimes (fetch + Web Crypto).
+ */
+export declare const SDK_VERSION = "0.2.0";
+/** The public API. Override `baseUrl` only to test against a local or staging site. */
+export declare const DEFAULT_BASE_URL = "https://discolisting.com/api/v1";
+export interface Server {
+  id: string;
+  guildId: string;
+  slug: string;
+  name: string;
+  shortDescription: string;
+  url: string;
+  inviteUrl: string | null;
+  iconUrl: string | null;
+  memberCount: number;
+  onlineCount: number;
+  qualityScore: number;
+  votes30d: number;
+  tags: string[];
+  category: string;
+  languages: string[];
+  nsfw: boolean;
+}
+export interface Bot {
+  id: string;
+  botId: string;
+  slug: string;
+  name: string;
+  shortDescription: string;
+  url: string;
+  inviteUrl: string;
+  iconUrl: string | null;
+  serverCount: number;
+  shardCount: number;
+  statsUpdatedAt: string | null;
+  qualityScore: number;
+  votes30d: number;
+  tags: string[];
+  prefix: string | null;
+  nsfw: boolean;
+}
+export interface VoteCheck {
+  /** True while the user's last vote for your listing is inside its cooldown. */
+  voted: boolean;
+  votedAt: string | null;
+  /** When the user can vote again (null if they have not voted recently). */
+  nextVoteAt: string | null;
+  /** Hours between votes: 24 for servers, 12 for bots. */
+  cooldownHours: number;
+}
+export interface VoteEntry {
+  userId: string;
+  votedAt: string;
+}
+export interface BotStatsInput {
+  serverCount: number;
+  shardCount?: number;
+  shardId?: number;
+}
+/** Body of a vote webhook delivery. */
+export interface VoteWebhook {
+  id: string;
+  event: 'vote' | 'test';
+  test: boolean;
+  data: {
+    type: 'vote' | 'test';
+    listingId: string;
+    /** Discord user ID of the voter. */
+    userId: string;
+    isWeekend: boolean;
+    votedAt: string;
+  };
+}
+export declare class ListingApiError extends Error {
+  status: number;
+  /** Seconds until the rate limit resets (429 only). */
+  retryAfter: number | null;
+  constructor(status: number, message: string,
+  /** Seconds until the rate limit resets (429 only). */
+  retryAfter?: number | null);
+}
+export interface ListingClientOptions {
+  /** Listing API key (lst_…), from your listing's Integrations page. Needed for vote checks and stats. */
+  apiKey?: string;
+  /** Defaults to https://discolisting.com/api/v1. Set it only for local or staging testing. */
+  baseUrl?: string;
+  fetch?: typeof fetch;
+  /** Request timeout in milliseconds (default 10 000). */
+  timeoutMs?: number;
+}
+export declare class ListingClient {
+  private readonly apiKey?;
+  private readonly baseUrl;
+  private readonly fetchImpl;
+  private readonly timeoutMs;
+  constructor(opts?: ListingClientOptions);
+  private request;
+  /** Look up a server by guild ID, listing ID or slug. */
+  getServer(id: string): Promise<Server>;
+  /** Look up a bot by bot ID, listing ID or slug. */
+  getBot(id: string): Promise<Bot>;
+  /** Did this Discord user vote for your listing within its cooldown (24 h servers, 12 h bots)? */
+  hasVoted(userId: string): Promise<VoteCheck>;
+  /** Recent votes, newest first. Pass the last `votedAt` as `before` to page. */
+  getVotes(opts?: {
+    limit?: number;
+    before?: string;
+  }): Promise<VoteEntry[]>;
+  /**
+   * Live SVG widget for a listing, for websites and READMEs (no API key needed).
+   * Mirrors the options on the listing's Integrations → Embed widget page.
+   */
+  widgetUrl(kind: 'server' | 'bot', slug: string, opts?: {
+    style?: 'card' | 'badge';
+    theme?: 'dark' | 'light';
+    /** Hex colour, with or without '#'. */
+    accent?: string;
+    stats?: ('members' | 'online' | 'votes' | 'score')[];
+  }): string;
+  /** Report your bot's server count (at most once a minute per shard). */
+  postStats(stats: BotStatsInput): Promise<{
+    serverCount: number;
+    shardCount: number;
+  }>;
+  /**
+   * Post stats now and then every `intervalMs` (default 30 minutes, minimum 1 minute).
+   * Returns a function that stops the timer. Errors go to `onError` and never throw.
+   */
+  autoPost(getStats: () => BotStatsInput | Promise<BotStatsInput>, opts?: {
+    intervalMs?: number;
+    onError?: (err: unknown) => void;
+  }): () => void;
+}
+/**
+ * Verify a vote webhook. Pass the raw request body (not re-serialised JSON), the
+ * `X-Listing-Signature` header and your signing secret. Rejects signatures older than
+ * `toleranceSeconds` (default 300) to stop replays.
+ */
+export declare function verifyWebhook(rawBody: string, signatureHeader: string | null | undefined, secret: string, opts?: {
+  toleranceSeconds?: number;
+  now?: number;
+}): Promise<boolean>;
+/** Verify and parse a webhook in one step; returns null when the signature is invalid. */
+export declare function parseWebhook(rawBody: string, signatureHeader: string | null | undefined, secret: string): Promise<VoteWebhook | null>;
+//#endregion

package/dist/index.d.ts

@@ -0,0 +1,148 @@
+//#region src/index.d.ts
+/**
+ * Official TypeScript SDK for the DiscoListing public API (https://discolisting.com/api/v1).
+ * Zero dependencies; works in Node 18+, Bun, Deno and edge runtimes (fetch + Web Crypto).
+ */
+export declare const SDK_VERSION = "0.2.0";
+/** The public API. Override `baseUrl` only to test against a local or staging site. */
+export declare const DEFAULT_BASE_URL = "https://discolisting.com/api/v1";
+export interface Server {
+  id: string;
+  guildId: string;
+  slug: string;
+  name: string;
+  shortDescription: string;
+  url: string;
+  inviteUrl: string | null;
+  iconUrl: string | null;
+  memberCount: number;
+  onlineCount: number;
+  qualityScore: number;
+  votes30d: number;
+  tags: string[];
+  category: string;
+  languages: string[];
+  nsfw: boolean;
+}
+export interface Bot {
+  id: string;
+  botId: string;
+  slug: string;
+  name: string;
+  shortDescription: string;
+  url: string;
+  inviteUrl: string;
+  iconUrl: string | null;
+  serverCount: number;
+  shardCount: number;
+  statsUpdatedAt: string | null;
+  qualityScore: number;
+  votes30d: number;
+  tags: string[];
+  prefix: string | null;
+  nsfw: boolean;
+}
+export interface VoteCheck {
+  /** True while the user's last vote for your listing is inside its cooldown. */
+  voted: boolean;
+  votedAt: string | null;
+  /** When the user can vote again (null if they have not voted recently). */
+  nextVoteAt: string | null;
+  /** Hours between votes: 24 for servers, 12 for bots. */
+  cooldownHours: number;
+}
+export interface VoteEntry {
+  userId: string;
+  votedAt: string;
+}
+export interface BotStatsInput {
+  serverCount: number;
+  shardCount?: number;
+  shardId?: number;
+}
+/** Body of a vote webhook delivery. */
+export interface VoteWebhook {
+  id: string;
+  event: 'vote' | 'test';
+  test: boolean;
+  data: {
+    type: 'vote' | 'test';
+    listingId: string;
+    /** Discord user ID of the voter. */
+    userId: string;
+    isWeekend: boolean;
+    votedAt: string;
+  };
+}
+export declare class ListingApiError extends Error {
+  status: number;
+  /** Seconds until the rate limit resets (429 only). */
+  retryAfter: number | null;
+  constructor(status: number, message: string,
+  /** Seconds until the rate limit resets (429 only). */
+  retryAfter?: number | null);
+}
+export interface ListingClientOptions {
+  /** Listing API key (lst_…), from your listing's Integrations page. Needed for vote checks and stats. */
+  apiKey?: string;
+  /** Defaults to https://discolisting.com/api/v1. Set it only for local or staging testing. */
+  baseUrl?: string;
+  fetch?: typeof fetch;
+  /** Request timeout in milliseconds (default 10 000). */
+  timeoutMs?: number;
+}
+export declare class ListingClient {
+  private readonly apiKey?;
+  private readonly baseUrl;
+  private readonly fetchImpl;
+  private readonly timeoutMs;
+  constructor(opts?: ListingClientOptions);
+  private request;
+  /** Look up a server by guild ID, listing ID or slug. */
+  getServer(id: string): Promise<Server>;
+  /** Look up a bot by bot ID, listing ID or slug. */
+  getBot(id: string): Promise<Bot>;
+  /** Did this Discord user vote for your listing within its cooldown (24 h servers, 12 h bots)? */
+  hasVoted(userId: string): Promise<VoteCheck>;
+  /** Recent votes, newest first. Pass the last `votedAt` as `before` to page. */
+  getVotes(opts?: {
+    limit?: number;
+    before?: string;
+  }): Promise<VoteEntry[]>;
+  /**
+   * Live SVG widget for a listing, for websites and READMEs (no API key needed).
+   * Mirrors the options on the listing's Integrations → Embed widget page.
+   */
+  widgetUrl(kind: 'server' | 'bot', slug: string, opts?: {
+    style?: 'card' | 'badge';
+    theme?: 'dark' | 'light';
+    /** Hex colour, with or without '#'. */
+    accent?: string;
+    stats?: ('members' | 'online' | 'votes' | 'score')[];
+  }): string;
+  /** Report your bot's server count (at most once a minute per shard). */
+  postStats(stats: BotStatsInput): Promise<{
+    serverCount: number;
+    shardCount: number;
+  }>;
+  /**
+   * Post stats now and then every `intervalMs` (default 30 minutes, minimum 1 minute).
+   * Returns a function that stops the timer. Errors go to `onError` and never throw.
+   */
+  autoPost(getStats: () => BotStatsInput | Promise<BotStatsInput>, opts?: {
+    intervalMs?: number;
+    onError?: (err: unknown) => void;
+  }): () => void;
+}
+/**
+ * Verify a vote webhook. Pass the raw request body (not re-serialised JSON), the
+ * `X-Listing-Signature` header and your signing secret. Rejects signatures older than
+ * `toleranceSeconds` (default 300) to stop replays.
+ */
+export declare function verifyWebhook(rawBody: string, signatureHeader: string | null | undefined, secret: string, opts?: {
+  toleranceSeconds?: number;
+  now?: number;
+}): Promise<boolean>;
+/** Verify and parse a webhook in one step; returns null when the signature is invalid. */
+export declare function parseWebhook(rawBody: string, signatureHeader: string | null | undefined, secret: string): Promise<VoteWebhook | null>;
+//#endregion

package/dist/index.js

@@ -0,0 +1,154 @@
+//#region src/index.ts
+/**
+* Official TypeScript SDK for the DiscoListing public API (https://discolisting.com/api/v1).
+* Zero dependencies; works in Node 18+, Bun, Deno and edge runtimes (fetch + Web Crypto).
+*/
+const SDK_VERSION = "0.2.0";
+/** The public API. Override `baseUrl` only to test against a local or staging site. */
+const DEFAULT_BASE_URL = "https://discolisting.com/api/v1";
+var ListingApiError = class extends Error {
+	status;
+	retryAfter;
+	constructor(status, message, retryAfter = null) {
+		super(message);
+		this.status = status;
+		this.retryAfter = retryAfter;
+		this.name = "ListingApiError";
+	}
+};
+var ListingClient = class {
+	apiKey;
+	baseUrl;
+	fetchImpl;
+	timeoutMs;
+	constructor(opts = {}) {
+		this.apiKey = opts.apiKey;
+		this.baseUrl = (opts.baseUrl || "https://discolisting.com/api/v1").replace(/\/+$/, "");
+		this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+		this.timeoutMs = opts.timeoutMs ?? 1e4;
+	}
+	async request(method, path, opts = {}) {
+		const url = new URL(`${this.baseUrl}${path}`);
+		for (const [k, v] of Object.entries(opts.query ?? {})) if (v !== void 0) url.searchParams.set(k, String(v));
+		const headers = {
+			Accept: "application/json",
+			"User-Agent": `listing-sdk/${SDK_VERSION}`
+		};
+		if (opts.auth) {
+			if (!this.apiKey) throw new ListingApiError(401, "This method needs an apiKey");
+			headers.Authorization = `Bearer ${this.apiKey}`;
+		}
+		if (opts.body !== void 0) headers["Content-Type"] = "application/json";
+		const res = await this.fetchImpl(url, {
+			method,
+			headers,
+			body: opts.body === void 0 ? void 0 : JSON.stringify(opts.body),
+			signal: AbortSignal.timeout(this.timeoutMs)
+		});
+		const data = await res.json().catch(() => ({}));
+		if (!res.ok) {
+			const retry = res.headers.get("retry-after");
+			throw new ListingApiError(res.status, data.error ?? res.statusText, retry ? Number(retry) : null);
+		}
+		return data;
+	}
+	/** Look up a server by guild ID, listing ID or slug. */
+	getServer(id) {
+		return this.request("GET", `/servers/${encodeURIComponent(id)}`);
+	}
+	/** Look up a bot by bot ID, listing ID or slug. */
+	getBot(id) {
+		return this.request("GET", `/bots/${encodeURIComponent(id)}`);
+	}
+	/** Did this Discord user vote for your listing within its cooldown (24 h servers, 12 h bots)? */
+	async hasVoted(userId) {
+		return this.request("GET", "/votes/check", {
+			query: { userId },
+			auth: true
+		});
+	}
+	/** Recent votes, newest first. Pass the last `votedAt` as `before` to page. */
+	async getVotes(opts = {}) {
+		return (await this.request("GET", "/votes", {
+			query: opts,
+			auth: true
+		})).votes;
+	}
+	/**
+	* Live SVG widget for a listing, for websites and READMEs (no API key needed).
+	* Mirrors the options on the listing's Integrations → Embed widget page.
+	*/
+	widgetUrl(kind, slug, opts = {}) {
+		const site = this.baseUrl.replace(/\/api\/v1$/, "");
+		const q = new URLSearchParams();
+		if (opts.style) q.set("style", opts.style);
+		if (opts.theme) q.set("theme", opts.theme);
+		if (opts.accent) q.set("accent", opts.accent.replace("#", ""));
+		if (opts.stats?.length) q.set("stats", opts.stats.join(","));
+		const qs = q.toString();
+		return `${site}/widget/${kind}/${encodeURIComponent(slug)}.svg${qs ? `?${qs}` : ""}`;
+	}
+	/** Report your bot's server count (at most once a minute per shard). */
+	postStats(stats) {
+		return this.request("POST", "/stats", {
+			body: stats,
+			auth: true
+		});
+	}
+	/**
+	* Post stats now and then every `intervalMs` (default 30 minutes, minimum 1 minute).
+	* Returns a function that stops the timer. Errors go to `onError` and never throw.
+	*/
+	autoPost(getStats, opts = {}) {
+		const interval = Math.max(6e4, opts.intervalMs ?? 18e5);
+		const run = async () => {
+			try {
+				await this.postStats(await getStats());
+			} catch (err) {
+				opts.onError?.(err);
+			}
+		};
+		run();
+		const timer = setInterval(() => void run(), interval);
+		timer.unref?.();
+		return () => clearInterval(timer);
+	}
+};
+function toHex(buf) {
+	return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function constantTimeEqual(a, b) {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return diff === 0;
+}
+/**
+* Verify a vote webhook. Pass the raw request body (not re-serialised JSON), the
+* `X-Listing-Signature` header and your signing secret. Rejects signatures older than
+* `toleranceSeconds` (default 300) to stop replays.
+*/
+async function verifyWebhook(rawBody, signatureHeader, secret, opts = {}) {
+	if (!signatureHeader) return false;
+	const parts = Object.fromEntries(signatureHeader.split(",").map((kv) => {
+		const i = kv.indexOf("=");
+		return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()];
+	}));
+	const t = Number(parts.t);
+	if (!parts.v1 || !Number.isFinite(t)) return false;
+	const now = opts.now ?? Math.floor(Date.now() / 1e3);
+	if (Math.abs(now - t) > (opts.toleranceSeconds ?? 300)) return false;
+	const enc = new TextEncoder();
+	const key = await globalThis.crypto.subtle.importKey("raw", enc.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return constantTimeEqual(toHex(await globalThis.crypto.subtle.sign("HMAC", key, enc.encode(`${String(t)}.${rawBody}`))), parts.v1);
+}
+/** Verify and parse a webhook in one step; returns null when the signature is invalid. */
+async function parseWebhook(rawBody, signatureHeader, secret) {
+	if (!await verifyWebhook(rawBody, signatureHeader, secret)) return null;
+	return JSON.parse(rawBody);
+}
+//#endregion
+export { DEFAULT_BASE_URL, ListingApiError, ListingClient, SDK_VERSION, parseWebhook, verifyWebhook };

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "discolisting",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Official TypeScript SDK for DiscoListing (discolisting.com): bot stats, vote checks, webhooks and widgets.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepublishOnly": "tsdown"
+  },
+  "devDependencies": {
+    "tsdown": "^0.23.0"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "bot-list",
+    "discolisting",
+    "discord",
+    "discord-bot",
+    "sdk",
+    "server-list",
+    "votes",
+    "webhooks"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://discolisting.com/api/docs#sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Generalcyno/Discord-listing.git",
+    "directory": "packages/sdk"
+  }
+}