@hawk.so/types 0.5.8 → 0.6.0-rc.1

package/.github/workflows/npm-publish.yml

@@ -17,7 +17,16 @@ jobs:
       - run: yarn
       - run: yarn lint
       - run: yarn build
-      - run: yarn publish --access=public
+      - name: Determine npm dist-tag
+        id: dist-tag
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          if echo "$VERSION" | grep -q "\-rc\."; then
+            echo "tag=rc" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=latest" >> "$GITHUB_OUTPUT"
+          fi
+      - run: yarn publish --access=public --tag ${{ steps.dist-tag.outputs.tag }}
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
   notify:

package/build/index.d.ts

@@ -10,6 +10,8 @@ export * from './src/base/event/taskManagerItem';
 export * from './src/base/event/addons';
 export * from './src/base/integrations/integrationToken';
 export * from './src/base/project/ProjectTaskManager';
+export * from './src/base/workspace/GitHubIntegration';
+export * from './src/base/user/GitHubAuthorization';
 export * from './src/dbScheme/businessOperation';
 export * from './src/dbScheme/groupedEvent';
 export * from './src/dbScheme/notificationsChannels';

package/build/index.js

@@ -26,6 +26,8 @@ __exportStar(require("./src/base/event/taskManagerItem"), exports);
 __exportStar(require("./src/base/event/addons"), exports);
 __exportStar(require("./src/base/integrations/integrationToken"), exports);
 __exportStar(require("./src/base/project/ProjectTaskManager"), exports);
+__exportStar(require("./src/base/workspace/GitHubIntegration"), exports);
+__exportStar(require("./src/base/user/GitHubAuthorization"), exports);
 __exportStar(require("./src/dbScheme/businessOperation"), exports);
 __exportStar(require("./src/dbScheme/groupedEvent"), exports);
 __exportStar(require("./src/dbScheme/notificationsChannels"), exports);

package/build/src/base/project/ProjectTaskManager.d.ts

@@ -48,7 +48,11 @@ export interface ProjectTaskManagerConfig {
      */
     config: {
         /**
-         * GitHub App installation ID
+         * GitHub App installation ID.
+         *
+         * This is a **copy** from workspace.integrations.github.installations[].
+         * Stored here for worker optimization — allows the worker to operate
+         * per-project without additional joins/lookups to the workspaces collection.
          */
         installationId: string;
         /**
@@ -60,57 +64,8 @@ export interface ProjectTaskManagerConfig {
          */
         repoFullName: string;
         /**
-         * Delegated user OAuth token for user-to-server authentication
-         * Used for creating issues and assigning Copilot on behalf of the user
+         * Primary programming language of the repository (as reported by GitHub)
          */
-        delegatedUser?: {
-            /**
-             * Hawk user ID who authorized the GitHub App
-             */
-            hawkUserId: string;
-            /**
-             * GitHub user ID
-             */
-            githubUserId: number;
-            /**
-             * GitHub username/login
-             */
-            githubLogin: string;
-            /**
-             * OAuth access token (user-to-server token)
-             */
-            accessToken: string;
-            /**
-             * Date when access token expires
-             * null if token expiration is disabled
-             */
-            accessTokenExpiresAt: Date | null;
-            /**
-             * OAuth refresh token
-             * Used to obtain new access tokens when they expire
-             */
-            refreshToken: string;
-            /**
-             * Date when refresh token expires
-             * null if refresh token expiration is disabled
-             */
-            refreshTokenExpiresAt: Date | null;
-            /**
-             * Date when token was created/saved
-             */
-            tokenCreatedAt: Date;
-            /**
-             * Date when token was last successfully validated
-             * null if never validated
-             */
-            tokenLastValidatedAt: Date | null;
-            /**
-             * Token status
-             * - active: token is valid (GET /user returns 200)
-             * - revoked: token was revoked (GET /user returns 401/403) or user removed authorization
-             * - missing: token is not present in project
-             */
-            status: 'active' | 'revoked' | 'missing';
-        };
+        repoLanguage?: string;
     };
 }

package/build/src/base/user/GitHubAuthorization.d.ts

@@ -0,0 +1,44 @@
+/**
+ * GitHub OAuth authorization stored at user level.
+ *
+ * accessToken is NOT stored persistently — it is obtained via refreshToken
+ * each time an action is needed on behalf of the user (e.g. Copilot assignment).
+ *
+ * GitHub may return a new refreshToken during refresh (token rotation),
+ * so it must be updated in the user document.
+ */
+export interface GitHubAuthorization {
+    /**
+     * GitHub user ID
+     */
+    githubUserId: number;
+    /**
+     * GitHub username/login
+     */
+    githubLogin: string;
+    /**
+     * OAuth refresh token.
+     * Used to obtain ephemeral access tokens on demand.
+     */
+    refreshToken: string;
+    /**
+     * Date when refresh token expires.
+     * null if refresh token expiration is disabled by GitHub.
+     */
+    refreshTokenExpiresAt: Date | null;
+    /**
+     * Date when this authorization (refreshToken) was originally created/saved
+     */
+    tokenCreatedAt: Date;
+    /**
+     * Date when refreshToken was last successfully used to obtain an accessToken.
+     * null if never validated after initial creation.
+     */
+    tokenLastValidatedAt: Date | null;
+    /**
+     * Token status:
+     * - 'active': token is valid
+     * - 'revoked': token was revoked or user removed authorization
+     */
+    status: 'active' | 'revoked';
+}

package/build/src/base/user/GitHubAuthorization.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/src/base/workspace/GitHubIntegration.d.ts

@@ -0,0 +1,93 @@
+/**
+ * GitHub App installation account info
+ */
+export interface GitHubInstallationAccount {
+    /**
+     * GitHub account ID
+     */
+    id: number;
+    /**
+     * GitHub account login (username or org name)
+     */
+    login: string;
+    /**
+     * Account type
+     */
+    type: 'User' | 'Organization';
+}
+/**
+ * Delegate user for agent operations (e.g. Copilot assignment).
+ * Points to a Hawk user who has an active GitHub authorization.
+ */
+export interface GitHubInstallationDelegatedUser {
+    /**
+     * Hawk user ID of the delegate
+     */
+    hawkUserId: string;
+    /**
+     * GitHub user ID of the delegate
+     */
+    githubUserId: number;
+    /**
+     * GitHub login of the delegate
+     */
+    githubLogin: string;
+    /**
+     * Delegate status:
+     * - 'active': delegate has a valid GitHub authorization
+     * - 'missing': no workspace member has a GitHub authorization
+     * - 'revoked': delegate's GitHub authorization was revoked
+     */
+    status: 'active' | 'missing' | 'revoked';
+}
+/**
+ * GitHub App installation record stored at workspace level.
+ *
+ * GitHub issues installationId per organization/account, not per repository.
+ * One workspace can have multiple installations
+ * (e.g. client's GitHub org + personal account).
+ */
+export interface GitHubInstallation {
+    /**
+     * GitHub App installation ID
+     */
+    installationId: number;
+    /**
+     * GitHub account where the App is installed
+     */
+    account: GitHubInstallationAccount;
+    /**
+     * Hawk user ID of who connected this installation (for audit)
+     */
+    connectedByHawkUserId: string;
+    /**
+     * Date when installation was connected
+     */
+    connectedAt: Date;
+    /**
+     * Date when installation record was last updated
+     */
+    updatedAt: Date;
+    /**
+     * Delegate user for agent actions in Worker
+     */
+    delegatedUser: GitHubInstallationDelegatedUser;
+}
+/**
+ * GitHub integration data stored at workspace level
+ */
+export interface WorkspaceGitHubIntegration {
+    /**
+     * List of GitHub App installations for this workspace
+     */
+    installations: GitHubInstallation[];
+}
+/**
+ * All integrations stored at workspace level
+ */
+export interface WorkspaceIntegrations {
+    /**
+     * GitHub integration (installations, etc.)
+     */
+    github?: WorkspaceGitHubIntegration;
+}

package/build/src/base/workspace/GitHubIntegration.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/src/dbScheme/notificationsChannels.d.ts

@@ -27,4 +27,8 @@ export interface NotificationsChannelsDBScheme {
      * Alerts through the Loop
      */
     loop?: NotificationsChannelSettingsDBScheme;
+    /**
+     * Alerts through a custom Webhook URL
+     */
+    webhook?: NotificationsChannelSettingsDBScheme;
 }

package/build/src/dbScheme/user.d.ts

@@ -3,6 +3,7 @@ import type { UserNotificationsDBScheme } from '../../index.ts';
 import type { BankCard } from './bankCard.ts';
 import type { MembershipDBScheme } from './membership.ts';
 import type { UserProjectsLastVisitDBScheme } from './userProjectsLastVisit.ts';
+import type { GitHubAuthorization } from '../base/user/GitHubAuthorization.ts';
 /**
  * Interface representing how user is stored in DB
  */
@@ -78,6 +79,11 @@ export interface UserDBScheme {
          */
         term?: string;
     };
+    /**
+     * GitHub OAuth authorizations.
+     * Used for user-to-server operations (e.g. Copilot assignment).
+     */
+    githubAuthorizations?: GitHubAuthorization[];
     /**
      * External identities for SSO (keyed by workspaceId)
      */

package/build/src/dbScheme/workspace.d.ts

@@ -1,5 +1,6 @@
 import type { ObjectId } from 'bson';
 import type { WorkspaceSsoConfig } from './sso.ts';
+import type { WorkspaceIntegrations } from '../base/workspace/GitHubIntegration.ts';
 /**
  * Workspace representation in DataBase
  */
@@ -73,4 +74,8 @@ export interface WorkspaceDBScheme {
      * SSO configuration (optional, only for workspaces with SSO enabled)
      */
     sso?: WorkspaceSsoConfig;
+    /**
+     * External integrations (GitHub, etc.)
+     */
+    integrations?: WorkspaceIntegrations;
 }

package/index.ts

@@ -14,6 +14,8 @@ export * from './src/base/event/addons';
 
 export * from './src/base/integrations/integrationToken';
 export * from './src/base/project/ProjectTaskManager';
+export * from './src/base/workspace/GitHubIntegration';
+export * from './src/base/user/GitHubAuthorization';
 
 export * from './src/dbScheme/businessOperation';
 export * from './src/dbScheme/groupedEvent';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hawk.so/types",
-  "version": "0.5.8",
+  "version": "0.6.0-rc.1",
   "description": "TypeScript definitions for Hawk",
   "types": "build/index.d.ts",
   "main": "build/index.js",

package/src/base/project/ProjectTaskManager.ts

@@ -57,7 +57,11 @@ export interface ProjectTaskManagerConfig {
    */
   config: {
     /**
-     * GitHub App installation ID
+     * GitHub App installation ID.
+     *
+     * This is a **copy** from workspace.integrations.github.installations[].
+     * Stored here for worker optimization — allows the worker to operate
+     * per-project without additional joins/lookups to the workspaces collection.
      */
     installationId: string;
 
@@ -72,66 +76,8 @@ export interface ProjectTaskManagerConfig {
     repoFullName: string;
 
     /**
-     * Delegated user OAuth token for user-to-server authentication
-     * Used for creating issues and assigning Copilot on behalf of the user
+     * Primary programming language of the repository (as reported by GitHub)
      */
-    delegatedUser?: {
-      /**
-       * Hawk user ID who authorized the GitHub App
-       */
-      hawkUserId: string;
-
-      /**
-       * GitHub user ID
-       */
-      githubUserId: number;
-
-      /**
-       * GitHub username/login
-       */
-      githubLogin: string;
-
-      /**
-       * OAuth access token (user-to-server token)
-       */
-      accessToken: string;
-
-      /**
-       * Date when access token expires
-       * null if token expiration is disabled
-       */
-      accessTokenExpiresAt: Date | null;
-
-      /**
-       * OAuth refresh token
-       * Used to obtain new access tokens when they expire
-       */
-      refreshToken: string;
-
-      /**
-       * Date when refresh token expires
-       * null if refresh token expiration is disabled
-       */
-      refreshTokenExpiresAt: Date | null;
-
-      /**
-       * Date when token was created/saved
-       */
-      tokenCreatedAt: Date;
-
-      /**
-       * Date when token was last successfully validated
-       * null if never validated
-       */
-      tokenLastValidatedAt: Date | null;
-
-      /**
-       * Token status
-       * - active: token is valid (GET /user returns 200)
-       * - revoked: token was revoked (GET /user returns 401/403) or user removed authorization
-       * - missing: token is not present in project
-       */
-      status: 'active' | 'revoked' | 'missing';
-    };
+    repoLanguage?: string;
   };
 }

package/src/base/user/GitHubAuthorization.ts

@@ -0,0 +1,50 @@
+/**
+ * GitHub OAuth authorization stored at user level.
+ *
+ * accessToken is NOT stored persistently — it is obtained via refreshToken
+ * each time an action is needed on behalf of the user (e.g. Copilot assignment).
+ *
+ * GitHub may return a new refreshToken during refresh (token rotation),
+ * so it must be updated in the user document.
+ */
+export interface GitHubAuthorization {
+  /**
+   * GitHub user ID
+   */
+  githubUserId: number;
+
+  /**
+   * GitHub username/login
+   */
+  githubLogin: string;
+
+  /**
+   * OAuth refresh token.
+   * Used to obtain ephemeral access tokens on demand.
+   */
+  refreshToken: string;
+
+  /**
+   * Date when refresh token expires.
+   * null if refresh token expiration is disabled by GitHub.
+   */
+  refreshTokenExpiresAt: Date | null;
+
+  /**
+   * Date when this authorization (refreshToken) was originally created/saved
+   */
+  tokenCreatedAt: Date;
+
+  /**
+   * Date when refreshToken was last successfully used to obtain an accessToken.
+   * null if never validated after initial creation.
+   */
+  tokenLastValidatedAt: Date | null;
+
+  /**
+   * Token status:
+   * - 'active': token is valid
+   * - 'revoked': token was revoked or user removed authorization
+   */
+  status: 'active' | 'revoked';
+}

package/src/base/workspace/GitHubIntegration.ts

@@ -0,0 +1,107 @@
+/**
+ * GitHub App installation account info
+ */
+export interface GitHubInstallationAccount {
+  /**
+   * GitHub account ID
+   */
+  id: number;
+
+  /**
+   * GitHub account login (username or org name)
+   */
+  login: string;
+
+  /**
+   * Account type
+   */
+  type: 'User' | 'Organization';
+}
+
+/**
+ * Delegate user for agent operations (e.g. Copilot assignment).
+ * Points to a Hawk user who has an active GitHub authorization.
+ */
+export interface GitHubInstallationDelegatedUser {
+  /**
+   * Hawk user ID of the delegate
+   */
+  hawkUserId: string;
+
+  /**
+   * GitHub user ID of the delegate
+   */
+  githubUserId: number;
+
+  /**
+   * GitHub login of the delegate
+   */
+  githubLogin: string;
+
+  /**
+   * Delegate status:
+   * - 'active': delegate has a valid GitHub authorization
+   * - 'missing': no workspace member has a GitHub authorization
+   * - 'revoked': delegate's GitHub authorization was revoked
+   */
+  status: 'active' | 'missing' | 'revoked';
+}
+
+/**
+ * GitHub App installation record stored at workspace level.
+ *
+ * GitHub issues installationId per organization/account, not per repository.
+ * One workspace can have multiple installations
+ * (e.g. client's GitHub org + personal account).
+ */
+export interface GitHubInstallation {
+  /**
+   * GitHub App installation ID
+   */
+  installationId: number;
+
+  /**
+   * GitHub account where the App is installed
+   */
+  account: GitHubInstallationAccount;
+
+  /**
+   * Hawk user ID of who connected this installation (for audit)
+   */
+  connectedByHawkUserId: string;
+
+  /**
+   * Date when installation was connected
+   */
+  connectedAt: Date;
+
+  /**
+   * Date when installation record was last updated
+   */
+  updatedAt: Date;
+
+  /**
+   * Delegate user for agent actions in Worker
+   */
+  delegatedUser: GitHubInstallationDelegatedUser;
+}
+
+/**
+ * GitHub integration data stored at workspace level
+ */
+export interface WorkspaceGitHubIntegration {
+  /**
+   * List of GitHub App installations for this workspace
+   */
+  installations: GitHubInstallation[];
+}
+
+/**
+ * All integrations stored at workspace level
+ */
+export interface WorkspaceIntegrations {
+  /**
+   * GitHub integration (installations, etc.)
+   */
+  github?: WorkspaceGitHubIntegration;
+}

package/src/dbScheme/notificationsChannels.ts

@@ -33,4 +33,9 @@ export interface NotificationsChannelsDBScheme {
    * Alerts through the Loop
    */
   loop?: NotificationsChannelSettingsDBScheme;
+
+  /**
+   * Alerts through a custom Webhook URL
+   */
+  webhook?: NotificationsChannelSettingsDBScheme;
 }

package/src/dbScheme/user.ts

@@ -3,6 +3,7 @@ import type { UserNotificationsDBScheme } from '../../index.ts';
 import type { BankCard } from './bankCard.ts';
 import type { MembershipDBScheme } from './membership.ts';
 import type { UserProjectsLastVisitDBScheme } from './userProjectsLastVisit.ts';
+import type { GitHubAuthorization } from '../base/user/GitHubAuthorization.ts';
 
 /**
  * Interface representing how user is stored in DB
@@ -95,6 +96,12 @@ export interface UserDBScheme {
     term?: string;
   };
 
+  /**
+   * GitHub OAuth authorizations.
+   * Used for user-to-server operations (e.g. Copilot assignment).
+   */
+  githubAuthorizations?: GitHubAuthorization[];
+
   /**
    * External identities for SSO (keyed by workspaceId)
    */

package/src/dbScheme/workspace.ts

@@ -1,5 +1,6 @@
 import type { ObjectId } from 'bson';
 import type { WorkspaceSsoConfig } from './sso.ts';
+import type { WorkspaceIntegrations } from '../base/workspace/GitHubIntegration.ts';
 
 /**
  * Workspace representation in DataBase
@@ -87,4 +88,9 @@ export interface WorkspaceDBScheme {
    * SSO configuration (optional, only for workspaces with SSO enabled)
    */
   sso?: WorkspaceSsoConfig;
+
+  /**
+   * External integrations (GitHub, etc.)
+   */
+  integrations?: WorkspaceIntegrations;
 }