topgg-api-types 0.0.1

package/dist/v1.d.ts

@@ -0,0 +1,333 @@
+import { n as Snowflake, t as ISO8601Date } from "./index-BzCAuhll.js";
+
+//#region src/v1/index.d.ts
+
+/**
+ * The type of a webhook event sent by Top.gg to your integration webhook endpoint.
+ *
+ * These are for events related to the integration connection itself (e.g., when it's created or deleted).
+ */
+type IntegrationWebhookEventType = "integration.create" | "integration.delete";
+/**
+ * The type of a project helps top.gg synchronize features.
+ * For example, a discord bot may have a support server, but this would not make any sense for a discord server.
+ *
+ * You can use this to further find out the specificity of the project.
+ */
+type ProjectType = "bot" | "server" | "game";
+/**
+ * A Platform is used to identify where the corresponding ID links towards.
+ */
+type ProjectPlatformType = "discord" | "roblox";
+/**
+ * A User Source is an enum that represents a user account from an external platform that is linked to a Top.gg user account.
+ * Each source has a unique identifer type that we might validate against.
+ *
+ * If none is passed to any endpoint that accepts a source parameter, it will default to topgg.
+ */
+type UserSource = "discord" | "topgg";
+/**
+ * Webhook scopes that are supported for integrations.
+ *
+ * These differ from integration webhook event types - these are the events that a user or you can subscribe to for an integration connection,
+ * while the integration webhook event types are the events that are sent to your webhook endpoint when something happens with your integration connection (e.g., it's created or deleted).
+ */
+type WebhookEventType = "webhook.test" | "vote.create";
+type WebhookEventTypes = WebhookEventType | IntegrationWebhookEventType;
+/**
+ * All error responses follow the [`application/problem+json`](https://datatracker.ietf.org/doc/html/rfc7807) specification.
+ */
+interface ErrorResponse {
+  type: string;
+  title: string;
+  status: number;
+  detail: string;
+}
+/**
+ * Represents a user on Top.gg.
+ */
+interface User {
+  /**
+   * The user's Top.gg ID.
+   */
+  id: Snowflake;
+  /**
+   * The user's platform ID (e.g., Discord ID).
+   */
+  platform_id: Snowflake;
+  /**
+   * The user's username.
+   */
+  name: string;
+  /**
+   * The URL of the user's avatar.
+   */
+  avatar_url: string;
+}
+/**
+ * Base project information shared across all project-related responses.
+ */
+interface BaseProject {
+  /**
+   * The project's Top.gg ID.
+   */
+  id: Snowflake;
+  /**
+   * The platform the project is on (e.g., "discord").
+   */
+  platform: ProjectPlatformType;
+  /**
+   * The platform-specific ID of the project (e.g., Discord Bot ID).
+   */
+  platform_id: Snowflake;
+  /**
+   * The type of project (e.g., "bot").
+   */
+  type: ProjectType;
+}
+/**
+ * Represents a vote on Top.gg.
+ */
+interface Vote {
+  /**
+   * The Top.gg ID of the user who voted.
+   */
+  user_id: Snowflake;
+  /**
+   * The user's ID on the project's platform (e.g., Discord ID).
+   */
+  platform_id: Snowflake;
+  /**
+   * The amount of votes this vote counted for.
+   */
+  weight: number;
+  /**
+   * The timestamp of when the user voted.
+   */
+  created_at: ISO8601Date;
+  /**
+   * The timestamp of when the vote expires (i.e., when the user can vote again).
+   * This is typically 12 hours after the `created_at` timestamp, but may vary based on the user's voting history and other factors.
+   */
+  expires_at: ISO8601Date;
+}
+/**
+ * Represents a vote for a specific project.
+ */
+type ProjectVote = Vote;
+/**
+ * Base structure for webhook payloads.
+ */
+interface WebhookPayloadBase<T extends WebhookEventTypes, Data extends object> {
+  type: T;
+  data: Data;
+}
+/**
+ * Data included when an integration connection is created.
+ */
+interface IntegrationCreateData {
+  /**
+   * The unique identifier for this integration connection.
+   */
+  connection_id: string;
+  /**
+   * The webhook secret used to verify webhook requests from Top.gg for this connection.
+   */
+  webhook_secret: string;
+  /**
+   * The project this integration is connected to.
+   */
+  project: BaseProject;
+  /**
+   * The user who created this integration connection.
+   */
+  user: User;
+}
+/**
+ * The payload delivered to your webhook endpoint when an integration connection is created.
+ * This will be sent if a user clicks "Connect" for your integration on the dashboard.
+ *
+ * @see https://docs.top.gg/docs/API/v1/integrations#2-topgg-sends-integrationcreate
+ */
+type IntegrationCreateWebhookPayload = WebhookPayloadBase<"integration.create", IntegrationCreateData>;
+/**
+ * The response you must return from your webhook endpoint when you receive an `integration.create` event.
+ * This tells Top.gg where to deliver webhook events for this integration connection and which events to deliver.
+ *
+ * @see https://docs.top.gg/docs/API/v1/integrations#3-respond-with-configuration
+ */
+interface IntegrationCreateResponse {
+  /**
+   * The URL where Top.gg should deliver webhook events for this connection.
+   */
+  webhook_url: string;
+  /**
+   * An array of webhook scopes to subscribe to.
+   *
+   * @see https://docs.top.gg/docs/API/v1/webhooks#supported-scopes
+   */
+  routes: WebhookEventTypes[];
+}
+/**
+ * Data included when an integration connection is deleted.
+ */
+interface IntegrationDeleteData {
+  /**
+   * The unique identifier for the integration connection that was deleted.
+   */
+  connection_id: string;
+}
+/**
+ * The payload delivered to your webhook endpoint when an integration connection is deleted.
+ */
+type IntegrationDeleteWebhookPayload = WebhookPayloadBase<"integration.delete", IntegrationDeleteData>;
+/**
+ * Data included when a vote is created.
+ */
+interface VoteCreateData extends Vote {
+  /**
+   * The project that was voted for.
+   */
+  project: BaseProject;
+  /**
+   * The user who voted.
+   */
+  user: User;
+}
+/**
+ * The payload delivered to your webhook endpoint when a user votes for your project and you have subscribed to the `vote.create` event.
+ */
+type VoteCreateWebhookPayload = WebhookPayloadBase<"vote.create", VoteCreateData>;
+/**
+ * Data included in a webhook test event.
+ */
+interface WebhookTestData {
+  /**
+   * A test user.
+   */
+  user: User;
+  /**
+   * A test project.
+   */
+  project: BaseProject;
+}
+/**
+ * The payload delivered to your webhook endpoint when you send a test webhook from the dashboard or via the API.
+ */
+type WebhookTestWebhookPayload = WebhookPayloadBase<"webhook.test", WebhookTestData>;
+/**
+ * Response for getting the authenticated project.
+ *
+ * - GET `/v1/projects/@me`
+ *
+ * @see https://docs.top.gg/docs/API/v1/projects#get-current-project
+ */
+interface GetProjectResponse extends BaseProject {
+  /**
+   * The project's name.
+   */
+  name: string;
+  /**
+   * The project's headline/tagline.
+   */
+  headline: string;
+  /**
+   * Tags associated with the project.
+   */
+  tags: string[];
+  /**
+   * The number of votes this month.
+   */
+  votes: number;
+  /**
+   * The total number of votes all time.
+   */
+  votes_total: number;
+  /**
+   * The average review score.
+   */
+  review_score: number;
+  /**
+   * The number of reviews.
+   */
+  review_count: number;
+}
+/**
+ * Query parameters for getting project votes.
+ *
+ * - GET `/v1/projects/@me/votes`
+ *
+ * Either `cursor` or `startDate` must be provided.
+ *
+ * @see https://docs.top.gg/docs/API/v1/projects/#get-votes
+ */
+interface GetProjectVotesQuery {
+  /**
+   * Pagination cursor for fetching the next page of votes. if provided, `startDate` is ignored.
+   *
+   * From the previous response.
+   */
+  cursor?: string;
+  /**
+   * The start date for fetching votes. Only votes created after this date will be returned. Required if `cursor` is not provided.
+   *
+   * Maximum 1 year in the past.
+   *
+   * ISO 8601 date string.
+   */
+  startDate?: string;
+}
+/**
+ * Response for the Get Project Votes endpoint.
+ *
+ * - GET `/v1/projects/@me/votes`
+ *
+ * @see https://docs.top.gg/docs/API/v1/projects/#get-votes
+ */
+interface GetProjectVotesResponse {
+  /**
+   * Cursor for fetching the next page of votes.
+   */
+  cursor: string;
+  /**
+   * An array of votes for the project.
+   */
+  data: ProjectVote[];
+}
+/**
+ * Query parameters for getting vote status by user.
+ *
+ * - GET `/v1/projects/@me/votes/:user_id`
+ *
+ * @see https://docs.top.gg/docs/API/v1/projects/#get-vote-status-by-user
+ */
+interface GetVoteStatusByUserQuery {
+  /**
+   * The source of the user ID. Defaults to "topgg".
+   */
+  source?: UserSource;
+}
+/**
+ * Response for the Get Vote Status By User endpoint.
+ *
+ * - GET `/v1/projects/@me/votes/:user_id`
+ *
+ * @see https://docs.top.gg/docs/API/v1/projects/#get-vote-status-by-user
+ */
+interface GetVoteStatusByUserResponse {
+  /**
+   * The timestamp of when the user last voted.
+   */
+  created_at: ISO8601Date;
+  /**
+   * The timestamp of when the user's vote expires (i.e., when they can vote again).
+   */
+  expires_at: ISO8601Date;
+  /**
+   * The amount of votes this vote counted for.
+   */
+  weight: number;
+}
+//#endregion
+export { BaseProject, ErrorResponse, GetProjectResponse, GetProjectVotesQuery, GetProjectVotesResponse, GetVoteStatusByUserQuery, GetVoteStatusByUserResponse, IntegrationCreateData, IntegrationCreateResponse, IntegrationCreateWebhookPayload, IntegrationDeleteData, IntegrationDeleteWebhookPayload, IntegrationWebhookEventType, ProjectPlatformType, ProjectType, ProjectVote, User, UserSource, Vote, VoteCreateData, VoteCreateWebhookPayload, WebhookEventType, WebhookEventTypes, WebhookPayloadBase, WebhookTestData, WebhookTestWebhookPayload };
+//# sourceMappingURL=v1.d.ts.map

package/dist/validators-B3dxgWHu.cjs

@@ -0,0 +1,54 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let zod_mini = require("zod/mini");
+zod_mini = __toESM(zod_mini);
+
+//#region src/utils/validators.ts
+const SnowflakeSchema = zod_mini.string().check(zod_mini.regex(/^\d{17,21}$/, "Invalid Snowflake ID"));
+const ISO8601DateSchema = zod_mini.iso.date();
+
+//#endregion
+Object.defineProperty(exports, 'ISO8601DateSchema', {
+  enumerable: true,
+  get: function () {
+    return ISO8601DateSchema;
+  }
+});
+Object.defineProperty(exports, 'SnowflakeSchema', {
+  enumerable: true,
+  get: function () {
+    return SnowflakeSchema;
+  }
+});
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});
+//# sourceMappingURL=validators-B3dxgWHu.cjs.map

package/dist/validators-B3dxgWHu.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators-B3dxgWHu.cjs","names":["z"],"sources":["../src/utils/validators.ts"],"sourcesContent":["import * as z from \"zod/mini\";\n\nexport const SnowflakeSchema = z.string().check(z.regex(/^\\d{17,21}$/, \"Invalid Snowflake ID\"));\nexport const ISO8601DateSchema = z.iso.date();\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEA,MAAa,kBAAkBA,SAAE,QAAQ,CAAC,MAAMA,SAAE,MAAM,eAAe,uBAAuB,CAAC;AAC/F,MAAa,oBAAoBA,SAAE,IAAI,MAAM"}

package/dist/validators-Mlu16sBg.js

@@ -0,0 +1,9 @@
+import * as z from "zod/mini";
+
+//#region src/utils/validators.ts
+const SnowflakeSchema = z.string().check(z.regex(/^\d{17,21}$/, "Invalid Snowflake ID"));
+const ISO8601DateSchema = z.iso.date();
+
+//#endregion
+export { SnowflakeSchema as n, ISO8601DateSchema as t };
+//# sourceMappingURL=validators-Mlu16sBg.js.map

package/dist/validators-Mlu16sBg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators-Mlu16sBg.js","names":[],"sources":["../src/utils/validators.ts"],"sourcesContent":["import * as z from \"zod/mini\";\n\nexport const SnowflakeSchema = z.string().check(z.regex(/^\\d{17,21}$/, \"Invalid Snowflake ID\"));\nexport const ISO8601DateSchema = z.iso.date();\n"],"mappings":";;;AAEA,MAAa,kBAAkB,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,eAAe,uBAAuB,CAAC;AAC/F,MAAa,oBAAoB,EAAE,IAAI,MAAM"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "topgg-api-types",
+  "author": {
+    "name": "The-LukeZ",
+    "email": "contact.lukez@proton.me",
+    "url": "https://github.com/The-LukeZ"
+  },
+  "type": "module",
+  "version": "0.0.1",
+  "license": "MIT",
+  "description": "Top.gg API types and validators for TypeScript",
+  "repository": {
+    "url": "https://github.com/The-LukeZ/topgg-api-types"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    },
+    "./v0": {
+      "require": "./dist/v0.cjs",
+      "import": "./dist/v0.js"
+    },
+    "./v0/validators": {
+      "require": "./dist/v0/validators.cjs",
+      "import": "./dist/v0/validators.js"
+    },
+    "./v1": {
+      "require": "./dist/v1.cjs",
+      "import": "./dist/v1.js"
+    },
+    "./v1/validators": {
+      "require": "./dist/v1/validators.cjs",
+      "import": "./dist/v1/validators.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "topgg",
+    "types",
+    "typescript",
+    "api"
+  ],
+  "devDependencies": {
+    "prettier": "3.8.1",
+    "tsdown": "^0.18.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "format": "prettier --write .",
+    "lint": "prettier --check ."
+  }
+}