patchwork-os 0.2.0-beta.1 → 0.2.0-beta.10.canary.95

package/dist/connectors/monday.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Monday.com connector — OAuth 2.0 + GraphQL v2.
+ *
+ * Endpoint: https://api.monday.com/v2 (single GraphQL endpoint).
+ * Auth:     OAuth 2.0 via auth.monday.com (MONDAY_CLIENT_ID / MONDAY_CLIENT_SECRET).
+ *
+ * Mirrors googleDocs.ts shape: secure token storage, OAuth state store,
+ * normalizeError categories, refresh-on-401 (Monday tokens do not currently
+ * advertise refresh tokens via the published flow — we still wire the path
+ * so a future scope addition Just Works).
+ */
+export interface MondayTokens {
+    access_token: string;
+    refresh_token?: string;
+    expiry_date?: number;
+    token_type?: string;
+    scope?: string;
+    name?: string;
+    email?: string;
+    connected_at: string;
+    _client_id?: string;
+    _client_secret?: string;
+}
+export interface ConnectorStatus {
+    id: string;
+    status: "connected" | "disconnected" | "needs_reauth";
+    lastSync?: string;
+    name?: string;
+    email?: string;
+}
+export interface ConnectorHandlerResult {
+    status: number;
+    body: string;
+    contentType?: string;
+    redirect?: string;
+}
+export type NormalizedErrorKind = "auth_expired" | "permission_denied" | "not_found" | "rate_limited" | "provider_error" | "unknown_error";
+export interface NormalizedError {
+    kind: NormalizedErrorKind;
+    status: number;
+    message: string;
+    retryable: boolean;
+}
+export declare function normalizeError(status: number, body: string): NormalizedError;
+/**
+ * Map a GraphQL error message string to a NormalizedError. Monday returns
+ * HTTP 200 on auth failures and embeds the failure as an `errors[]` entry
+ * — we need a separate classifier from the HTTP-status one.
+ */
+export declare function normalizeGraphQLError(message: string): NormalizedError;
+export declare function loadTokens(): MondayTokens | null;
+export declare function getStatus(): ConnectorStatus;
+export declare function getValidAccessToken(): Promise<string>;
+export interface GraphQLError {
+    message: string;
+    path?: Array<string | number>;
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Authenticated GraphQL POST to https://api.monday.com/v2.
+ *
+ * Monday returns HTTP 200 even when the GraphQL operation failed; the
+ * `errors` array must be inspected separately. Auth-shaped errors there
+ * are mapped via normalizeGraphQLError so callers see a consistent
+ * NormalizedErrorKind.
+ *
+ * Refresh-on-401 path is wired even though current Monday OAuth flows
+ * tend not to issue refresh tokens — when a refresh token IS present
+ * (e.g. enterprise / future scope) the retry-once path takes over.
+ */
+export declare function graphqlCall<T = unknown>(query: string, variables?: Record<string, unknown>, fetchFn?: typeof fetch): Promise<T>;
+export interface MondayUser {
+    id: string;
+    name?: string;
+    email?: string;
+    url?: string;
+}
+export interface MondayWorkspace {
+    id: string;
+    name?: string;
+}
+export interface MondayBoardSummary {
+    id: string;
+    name: string;
+    description?: string;
+    state?: string;
+    board_kind?: string;
+    workspace?: MondayWorkspace | null;
+}
+export interface MondayColumn {
+    id: string;
+    title?: string;
+    type?: string;
+}
+export interface MondayGroup {
+    id: string;
+    title?: string;
+}
+export interface MondayBoardDetail extends MondayBoardSummary {
+    columns?: MondayColumn[];
+    groups?: MondayGroup[];
+    items_count?: number;
+}
+export interface MondayColumnValue {
+    id: string;
+    text?: string | null;
+    value?: string | null;
+    type?: string;
+}
+export interface MondayUpdateReply {
+    id: string;
+    body?: string;
+    created_at?: string;
+}
+export interface MondayUpdate {
+    id: string;
+    body?: string;
+    created_at?: string;
+    replies?: MondayUpdateReply[];
+}
+export interface MondayItemSummary {
+    id: string;
+    name: string;
+    state?: string;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface MondayItemDetail extends MondayItemSummary {
+    board?: {
+        id: string;
+        name?: string;
+    };
+    group?: MondayGroup;
+    column_values?: MondayColumnValue[];
+    subitems?: MondayItemSummary[];
+    updates?: MondayUpdate[];
+}
+export interface MondayItemsPage {
+    cursor: string | null;
+    items: MondayItemSummary[];
+}
+export declare function me(fetchFn?: typeof fetch): Promise<MondayUser>;
+export declare function listBoards(limit?: number, fetchFn?: typeof fetch): Promise<MondayBoardSummary[]>;
+export declare function getBoard(boardId: string, fetchFn?: typeof fetch): Promise<MondayBoardDetail | null>;
+export declare function listItems(boardId: string, limit?: number, cursor?: string, fetchFn?: typeof fetch): Promise<MondayItemsPage>;
+export declare function getItem(itemId: string, fetchFn?: typeof fetch): Promise<MondayItemDetail | null>;
+export declare function getUpdates(itemId: string, limit?: number, fetchFn?: typeof fetch): Promise<MondayUpdate[]>;
+export declare function searchByName(boardId: string, query: string, fetchFn?: typeof fetch): Promise<MondayItemsPage>;
+export interface MondayCreatedItem {
+    id: string;
+    name: string;
+}
+export interface MondayMutationId {
+    id: string;
+}
+export interface MondayCreatedUpdate {
+    id: string;
+    body: string;
+    created_at: string;
+}
+export interface MondayWebhook {
+    id: string;
+    board_id: string;
+}
+export type MondayWebhookEvent = "create_item" | "change_column_value" | "change_status_column_value" | "create_update" | "move_item_to_group";
+/**
+ * Create a new item on a board.
+ * `columnValues` is a JSON-encoded string of column values
+ * (e.g. `JSON.stringify({ status: { label: "Done" } })`).
+ */
+export declare function createItem(boardId: string, groupId: string, itemName: string, columnValues?: string, fetchFn?: typeof fetch): Promise<MondayCreatedItem>;
+/**
+ * Update a column value using the JSON-based mutation (complex column types).
+ * `value` must be a JSON-encoded string (e.g. `JSON.stringify({ label: "Done" })`).
+ */
+export declare function updateColumnValue(boardId: string, itemId: string, columnId: string, value: string, fetchFn?: typeof fetch): Promise<MondayMutationId>;
+/**
+ * Update a column using simple string/number values
+ * (no JSON encoding required for the value itself).
+ */
+export declare function changeItemColumn(boardId: string, itemId: string, columnId: string, value: string, fetchFn?: typeof fetch): Promise<MondayMutationId>;
+/** Move an item to a different group on the same board. */
+export declare function moveItemToGroup(itemId: string, groupId: string, fetchFn?: typeof fetch): Promise<MondayMutationId>;
+/** Permanently delete an item. */
+export declare function deleteItem(itemId: string, fetchFn?: typeof fetch): Promise<MondayMutationId>;
+/** Post a text update (comment) on an item. */
+export declare function createUpdate(itemId: string, body: string, fetchFn?: typeof fetch): Promise<MondayCreatedUpdate>;
+/**
+ * Register a Monday.com webhook on a board.
+ * `event` must be one of the MondayWebhookEvent values.
+ * `columnId` is required for `change_column_value` / `change_status_column_value` events.
+ */
+export declare function createWebhook(boardId: string, url: string, event: MondayWebhookEvent, columnId?: string, fetchFn?: typeof fetch): Promise<MondayWebhook>;
+/** Delete a Monday.com webhook by its ID. */
+export declare function deleteWebhook(webhookId: string, fetchFn?: typeof fetch): Promise<MondayMutationId>;
+/**
+ * Verify an incoming Monday.com webhook request.
+ *
+ * Monday sends the signing secret directly in the `Authorization` header
+ * (no "Bearer" prefix). Compare with constant-time equality to prevent
+ * timing attacks.
+ *
+ * @param rawBody          - Raw request body string (before JSON.parse).
+ * @param authorizationHeader - Value of the `Authorization` header from the
+ *                           incoming request (may be undefined/null).
+ * @param signingSecret    - The webhook signing secret configured on Monday.
+ * @returns true when the header matches the secret.
+ */
+export declare function verifyMondayWebhook(_rawBody: string, authorizationHeader: string | null | undefined, signingSecret: string): boolean;
+export declare function handleMondayAuthRedirect(): ConnectorHandlerResult;
+export declare function handleMondayCallback(code: string | null, state: string | null, error: string | null): Promise<ConnectorHandlerResult>;
+/**
+ * Health check: POST `{ me { id name email } }` and verify the response
+ * contains a non-empty `data.me` envelope.
+ */
+export declare function handleMondayTest(): Promise<ConnectorHandlerResult>;
+export declare function handleMondayDisconnect(): Promise<ConnectorHandlerResult>;