feat: add webhook interfaces

Close #8

src/constants/index.ts

@@ -0,0 +1,3 @@
+export * from './webhook-challenge-actions';
+export * from './webhook-user-actions';
+export * from './codewars-error-codes';

src/constants/webhook-challenge-actions.ts

@@ -0,0 +1,29 @@
+/**
+ * Static list of all currently known webhook challenge actions.
+ *
+ * **note** not sure if `updated` is a value, as its not documented.
+ *
+ * Represented as type `WebhookChallengeActions`
+ *
+ * Further documentation is here:
+ * https://dev.codewars.com/?shell#code-challenges
+ *
+ *
+ */
+export const WEBHOOK_CHALLENGE_ACTIONS = Object.freeze([
+  'created',
+  'approved',
+  'voted',
+  'solution_finalized'
+] as const);
+
+/**
+ * Type representing all the webhook challenge actions.
+ *
+ * - created - Code challenge was created
+ * - approved - Code challenge was successfully approved (no longer in beta state)
+ * - voted - Someone voted on the code challenge. Does not specify what type of vote
+ * - solution_finalized - Someone submitted a solution to the code challenge
+ */
+export type WebhookChallengeActions =
+  (typeof WEBHOOK_CHALLENGE_ACTIONS)[number];

src/constants/webhook-user-actions.ts

@@ -0,0 +1,20 @@
+/**
+ * Static list of all currently known webhook user actions.
+ *
+ * Represented as type `WebhookUserActions`
+ *
+ * Further documentation is here:
+ * https://dev.codewars.com/?shell#user
+ */
+export const WEBHOOK_USER_ACTIONS = Object.freeze([
+  'rank_earned',
+  'honor_changed'
+] as const);
+
+/**
+ * Type representing all the webhook user actions.
+ *
+ * - rank_earned - The user's rank has been upgraded. Could be a global rank, or a language rank
+ * - honor_changed - User's honor changed (usually in a positive direction)
+ */
+export type WebhookUserActions = (typeof WEBHOOK_USER_ACTIONS)[number];

src/index.ts

@@ -1,5 +1,4 @@
-// barrel exports, not sure if this is smart or not
-export * from './constants/codewars-error-codes';
+export * from './constants';
 export * from './errors';
 export * from './types';
 export * from './utils/codewars-api';

src/types/index.ts

@@ -9,3 +9,6 @@ export * from './user';
 export * from './user-code-challenges';
 export * from './user-rank';
 export * from './user-ranks';
+export * from './webhook-challenge-event';
+export * from './webhook-update-event';
+export * from './webhook-user-event';

src/types/user.ts

@@ -5,6 +5,11 @@
 import { UserCodeChallenges } from './user-code-challenges';
 import { UserRanks } from './user-ranks';
 
+/**
+ * The user's information
+ *
+ * TODO: not sure how `id` works, but should be included?
+ */
 export interface User {
   /**
    * Username of the user.

src/types/webhook-challenge-event.ts

@@ -0,0 +1,52 @@
+import { WebhookChallengeActions } from '../constants';
+import { CodeChallenge } from './code-challenge';
+import { User } from './user';
+
+/**
+ * Type representing the webhook challenge events
+ *
+ * Further documentation is here:
+ * https://dev.codewars.com/?shell#code-challenges
+ *
+ * Headers:
+ * ```
+ * User-Agent: Codewars Hookbot
+ * Content-Type: application/json
+ * X-Webhook-Event: code_challenge
+ * X-Webhook-Secret: <secret>
+ * ```
+ *
+ * TODO: add solution_finalized version
+ */
+export interface WebhookChallengeEvent {
+  /**
+   * The action that triggered the webhook
+   */
+  action: WebhookChallengeActions;
+  /**
+   * The code challenge that was affected by the action
+   */
+  code_challenge: {
+    /**
+     * The id of the code challenge.
+     */
+    id: CodeChallenge['id'];
+    /**
+     * Id of the webhook that created and sent this event.
+     */
+    created_by_id: string;
+  };
+  solution_finalized?: {
+    /**
+     * The id of the code challenge where the solution is finalized.
+     */
+    id: CodeChallenge['id'];
+
+    /**
+     * The user's id
+     *
+     * TODO: not sure where else this is used.
+     */
+    user_id: string;
+  };
+}

src/types/webhook-update-event.ts

@@ -0,0 +1,30 @@
+/**
+ * Type representing the event returned when a webhook is
+ * created.
+ *
+ * This is sent once a webhook is setup.
+ *
+ * Headers:
+ * ```
+ * User-Agent: Codewars Hookbot
+ * Content-Type: application/json
+ * X-Webhook-Event: webhook
+ * X-Webhook-Secret: <secret>
+ * ```
+ */
+export interface WebhookUpdateEvent {
+  /**
+   * Once
+   */
+  action: 'updated';
+  /**
+   * Information on the webhook created
+   */
+  webhook: {
+    /**
+     * The id of the webhook, will be returned in other
+     * events.
+     */
+    id: string;
+  };
+}

src/types/webhook-user-event.ts

@@ -0,0 +1,53 @@
+import { WebhookUserActions } from '../constants';
+
+/**
+ * Type representing the generic webhook user events
+ */
+export interface WebhookUserEvent {
+  /**
+   * The action that triggered this webhook
+   */
+  action: WebhookUserActions;
+
+  /**
+   * The user that was affected by the action
+   */
+  user: {
+    /**
+     * The id of the user
+     */
+    id: string;
+  };
+}
+
+export interface WebhookUserRankEarnedEvent extends WebhookUserEvent {
+  action: 'rank_earned';
+  /**
+   * The user that was affect by the action
+   */
+  user: {
+    id: string;
+    /**
+     * The rank that the user earned, could be language or global rank
+     */
+    rank: number;
+  };
+}
+
+export interface WebhookUserHonorChangedEvent extends WebhookUserEvent {
+  action: 'honor_changed';
+  /**
+   * The user that was affect by the action
+   */
+  user: {
+    id: string;
+    /**
+     * The overall honor the user has
+     */
+    honor: number;
+    /**
+     * The change in honor the user has had (usually in a positive direction)
+     */
+    honor_delta: number;
+  };
+}