@nurama/sdk 0.0.0-stage → 1.4.0

package/src/routes/user.ts

@@ -0,0 +1,214 @@
+import NuramaClient from '../NuramaClient.js';
+import { type User, type PublicUser } from '@nurama/types';
+
+export interface FileData { 
+    name: string;
+    checksum: string;
+    sizeInMB: number;
+}
+
+// Define the type for the update data based on backend validation
+export interface UpdateUserData {
+  email?: string;
+  userName?: string;
+  password?: string;
+  firstName?: string;
+  middleName?: string;
+  lastName?: string;
+  company?: string;
+  displayName?: string;
+  color?: string;
+  allowOauthAutolink?: boolean;
+}
+
+export interface PreferencesData {
+    hide?: string[];
+    // Per-user UX dismissals — anything the user has explicitly opted
+    // out of seeing again. The BE merges this object one level deep, so a
+    // write to one `dismissed.*` key preserves its siblings. For each
+    // inner array the server treats the value as the full list — callers
+    // should merge the new id into the existing array before sending.
+    dismissed?: {
+      todos?: string[];
+    };
+    // Daily-tips carousel state. `disabled` opts out entirely; `lastShownDate`
+    // (local `YYYY-MM-DD`) gates the once-per-day rule cumulatively across
+    // workspaces and devices. Merged one level deep by the BE.
+    dailyTips?: {
+      disabled?: boolean;
+      lastShownDate?: string;
+    };
+    // Per-project feature-intro tutorials the user has seen, keyed by project
+    // id. Merged one level deep by the BE.
+    featureIntros?: Record<string, string[]>;
+    // Preferred date display format. Seeded at registration from the
+    // registrant's country (European unless month-first, e.g. the US → american);
+    // European is the fallback when unset. User-overridable, incl. ISO (YYYY-MM-DD).
+    dateFormat?: 'european' | 'american' | 'iso';
+    // Add other preferences
+}
+
+// Structural shape only — visible strings are looked up on the FE by
+// `id` against the `auth.todos.<id>.{title,description,actionLabel}`
+// i18n keys. Keeps the backend response language-agnostic.
+export interface UserTodo {
+  id: string;
+  dismissible: boolean;
+}
+
+/**
+ * Defines user-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the user-related methods.
+ */
+export default function createUserMethods(client: NuramaClient) {
+  // Specify return type more accurately if possible, using UserMethods interface
+  return {
+    /**
+     * Retrieves the public profile of a specific user.
+     * Requires authentication.
+     * @param {string} userId - The ID of the user to retrieve.
+     * @returns {Promise<object>} Public user object.
+     */
+    async getUser(userId: string): Promise<PublicUser> {
+      if (!userId) {
+        throw new Error('userId is required.');
+      }
+      return client._request({
+        method: 'GET',
+        endpoint: `/v1/users/${userId}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Retrieves the current user's profile.
+     * Requires authentication.
+     * @returns {Promise<PublicUser>} The current user's profile.
+     * @throws {Error} If no user ID is found in the token.
+     */
+    async getSelf(): Promise<PublicUser> {
+      return client._request({
+        method: 'GET',
+        endpoint: '/v1/users',
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Deletes the current user.
+     * Requires authentication.
+     * @returns {Promise<void>}
+     */
+    async deleteCurrentUser(): Promise<void> {
+      return client._request({
+        method: 'DELETE',
+        endpoint: '/v1/users',
+        sendJWT: true,
+      });
+    },
+    /**
+     * Updates the user's avatar.
+     * @param {object} fileData - File metadata (e.g., { name, checksum, sizeInMB }).
+     * @returns {Promise<object>} Object containing signed URL data and updated user info.
+     */
+    async updateAvatar(fileData: FileData): Promise<any> {
+      return client._request({
+        method: 'PUT',
+        endpoint: '/v1/users/avatar',
+        body: fileData,
+        sendJWT: true,
+      });
+    },
+    /**
+     * Creates a new avatar for the user.
+     * @param {object} fileData - File metadata (e.g., { name, checksum, sizeInMB }).
+     * @returns {Promise<object>} Object containing signed URL data and updated user info.
+     */
+    async createAvatar(fileData: FileData): Promise<any> {
+      return client._request({
+        method: 'POST',
+        endpoint: '/v1/users/avatar',
+        body: fileData,
+        sendJWT: true,
+      });
+    },
+    /**
+     * Updates the user's preferences.
+     * @param {object} preferenceData - Preference data to update (e.g., { hide: ['feedHint'] }).
+     * @returns {Promise<object>} Updated user object.
+     */
+    async updatePreferences(preferenceData: PreferencesData): Promise<User> {
+      return client._request({
+        method: 'PATCH',
+        endpoint: '/v1/users/preferences',
+        body: preferenceData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Record that the current user has seen a one-time UI element (welcome
+     * video, tutorial coachmark). Idempotent. Returns the updated user.
+     * @param {string} element - one-time element key (see backend oneTimeElements).
+     */
+    async markSeen(element: string): Promise<User> {
+      return client._request({
+        method: 'POST',
+        endpoint: '/v1/users/has-seen',
+        body: { element },
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Remove one-time UI elements from the current user's `hasSeen` so they
+     * display again. Pass specific element keys, or omit to clear ALL.
+     * Returns the updated user.
+     * @param {string[]} [elements] - elements to remove; omit to clear all.
+     */
+    async unmarkSeen(elements?: string[]): Promise<User> {
+      return client._request({
+        method: 'DELETE',
+        endpoint: '/v1/users/has-seen',
+        body: elements ? { elements } : {},
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Updates the logged-in user's profile.
+     * Requires authentication.
+     * At least one field must be provided.
+     * @param {UpdateUserData} updateData - The user data fields to update.
+     * @returns {Promise<User>} The updated user object.
+     */
+    async updateSelf(updateData: UpdateUserData): Promise<User> {
+      // Ensure at least one key is present, matching backend validation .min(1)
+      if (Object.keys(updateData).length === 0) {
+        throw new Error('At least one field must be provided to update the user.');
+      }
+      return client._request<User>({
+        method: 'PATCH',
+        endpoint: '/v1/users', // Endpoint for updating the logged-in user
+        body: updateData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Get the current user's active site-level Todos for the onboarding
+     * drawer. Returns only todos whose completion condition isn't met and
+     * (for dismissibles) that the user hasn't opted out of. Server
+     * computes from live state — no caching on the server side, so a
+     * fresh call always reflects ground truth.
+     */
+    async getTodos(): Promise<{ todos: UserTodo[] }> {
+      return client._request<{ todos: UserTodo[] }>({
+        method: 'GET',
+        endpoint: '/v1/users/todos',
+        sendJWT: true,
+      });
+    },
+  };
+} 

package/src/routes/version.ts

@@ -0,0 +1,62 @@
+import NuramaClient from '../NuramaClient.js';
+
+// --- Response Interfaces ---
+export interface CommitResponse {
+  buildCommit: string;
+}
+
+export interface HealthStatus {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  /** Epoch milliseconds when the check ran. */
+  timestamp: number;
+  /** Process uptime in seconds. */
+  uptime: number;
+  /** Present when status is `degraded` or `unhealthy`. */
+  reason?: string;
+  postgres: { status: 'connected' | 'disconnected'; [key: string]: unknown };
+  memory: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+// --- Method Definitions ---
+
+/**
+ * Defines version-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the version-related methods.
+ */
+export default function createVersionMethods(client: NuramaClient) {
+  return {
+    /**
+     * Retrieves the latest git commit hash of the deployed application.
+     * This is a public endpoint and does not require authentication.
+     * @returns {Promise<CommitResponse>} An object containing the buildCommit hash.
+     */
+    async getCommitHash(): Promise<CommitResponse> {
+      return client._request<CommitResponse>({
+        method: 'GET',
+        endpoint: '/v1/version/commit',
+        sendJWT: false,
+      });
+    },
+
+    /**
+     * Retrieves the API health report (database connectivity, memory, uptime).
+     * Public endpoint. Resolves normally for `healthy` and `degraded`; the API
+     * responds 503 for `unhealthy`, which surfaces as a thrown error with `status: 503`
+     * and the report on `data`.
+     * @returns {Promise<HealthStatus>} The health report.
+     */
+    async getHealth(): Promise<HealthStatus> {
+      return client._request<HealthStatus>({
+        method: 'GET',
+        endpoint: '/v1/version/health',
+        sendJWT: false,
+        bypassCache: true,
+      });
+    },
+  };
+}
+
+// --- Export Method Type ---
+export type VersionMethods = ReturnType<typeof createVersionMethods>;

package/src/routes/webhook.ts

@@ -0,0 +1,295 @@
+import NuramaClient from '../NuramaClient.js';
+
+/**
+ * Wire-format webhook event names. Mirrors the backend's
+ * `@config/webhookEvents` registry. New events land here and on the
+ * backend together; the additive-only payload contract means receivers
+ * pinned to a specific event name keep working as fields are added.
+ */
+export type WebhookEvent =
+  | 'task.created'
+  | 'task.updated'
+  | 'task.deleted'
+  | 'chat.message.created'
+  | 'asset.published'
+  | 'webhook.test';
+
+export type WebhookSubscriptionStatus = 'active' | 'paused' | 'failedOut';
+
+/**
+ * Public shape of a webhook subscription. Never includes the signing
+ * secret or the encrypted ciphertext — those are server-only fields.
+ */
+export interface WebhookSubscription {
+  id: string;
+  workspaceId: string;
+  appId?: string | null;
+  name: string;
+  url: string;
+  events: WebhookEvent[];
+  status: WebhookSubscriptionStatus;
+  failedOutAt?: string | null;
+  failedOutReason?: string | null;
+  /**
+   * Optional expiration. When set and in the past, the worker stops
+   * fanning new attempts to this subscription, and any in-flight
+   * attempts DLQ with a clear reason rather than retrying. Null = no
+   * expiry; the subscription delivers indefinitely until manually
+   * paused or deleted.
+   */
+  expiresAt?: string | null;
+  createdAt: string;
+  updatedAt: string;
+  createdById: string;
+  lastDeliveryAt?: string | null;
+  lastSuccessAt?: string | null;
+  lastFailureAt?: string | null;
+}
+
+export interface CreateWebhookData {
+  name: string;
+  url: string;
+  events: WebhookEvent[];
+  /** Optional ISO timestamp. Must be in the future when set. */
+  expiresAt?: string | null;
+}
+
+export interface UpdateWebhookData {
+  name?: string;
+  url?: string;
+  events?: WebhookEvent[];
+  status?: 'active' | 'paused';
+  /** Pass null to clear an existing expiry; pass a future ISO date to set / extend. */
+  expiresAt?: string | null;
+}
+
+export interface CreateWebhookResponse {
+  subscription: WebhookSubscription;
+  /**
+   * The HMAC signing secret. Returned ONLY here (and from
+   * `rotateWebhookSecret`). The server keeps the ciphertext on the row
+   * and cannot recover the plaintext later — the customer must capture
+   * it now or rotate.
+   */
+  signingSecret: string;
+}
+
+export interface RotateWebhookSecretResponse extends CreateWebhookResponse {}
+
+export type WebhookAttemptStatus = 'pending' | 'inflight' | 'succeeded' | 'failed' | 'dlq';
+
+export interface WebhookAttempt {
+  id: string;
+  notificationId: string;
+  subscriptionId: string;
+  attempt: number;
+  maxAttempts: number;
+  status: WebhookAttemptStatus;
+  signatureV1: string;
+  scheduledAt: string;
+  startedAt?: string | null;
+  deliveredAt?: string | null;
+  nextRetryAt?: string | null;
+  responseCode?: number | null;
+  responseBody?: string | null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  responseHeaders?: Record<string, any> | null;
+  errorMessage?: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ListDeliveriesParams {
+  limit?: number;
+  cursor?: string;
+  status?: WebhookAttemptStatus;
+}
+
+export interface ListDeliveriesResponse {
+  items: WebhookAttempt[];
+  nextCursor: string | null;
+}
+
+export interface TestWebhookResponse {
+  queued: true;
+  message: string;
+}
+
+/**
+ * Outbound webhook subscription management. Admin-gated server-side
+ * by `canManageWebhooks`. All operations are workspace-scoped — there
+ * is no app-owned surface here yet (Phase 3 / OAuth).
+ */
+export default function createWebhookMethods(client: NuramaClient) {
+  return {
+    /**
+     * Create a webhook subscription. The signing secret is in the
+     * response's `secret` field — store it immediately, it cannot be
+     * retrieved again.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    async createWebhook(
+      workspaceId: string,
+      data: CreateWebhookData,
+    ): Promise<CreateWebhookResponse> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request<CreateWebhookResponse>({
+        method: 'POST',
+        endpoint: `/v1/workspaces/${workspaceId}/webhooks`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * List webhook subscriptions in a workspace. Secrets are never returned.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    async listWebhooks(workspaceId: string): Promise<WebhookSubscription[]> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request<WebhookSubscription[]>({
+        method: 'GET',
+        endpoint: `/v1/workspaces/${workspaceId}/webhooks`,
+        sendJWT: true,
+        bypassCache: true,
+      });
+    },
+
+    /**
+     * Fetch a single webhook subscription by id.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    async getWebhook(workspaceId: string, webhookId: string): Promise<WebhookSubscription> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!webhookId) throw new Error('webhookId is required.');
+      return client._request<WebhookSubscription>({
+        method: 'GET',
+        endpoint: `/v1/workspaces/${workspaceId}/webhooks/${webhookId}`,
+        sendJWT: true,
+        bypassCache: true,
+      });
+    },
+
+    /**
+     * Update a webhook subscription's url, event filter, or active state.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    async updateWebhook(
+      workspaceId: string,
+      webhookId: string,
+      data: UpdateWebhookData,
+    ): Promise<WebhookSubscription> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!webhookId) throw new Error('webhookId is required.');
+      return client._request<WebhookSubscription>({
+        method: 'PATCH',
+        endpoint: `/v1/workspaces/${workspaceId}/webhooks/${webhookId}`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Delete a webhook subscription. In-flight deliveries continue to
+     * the receiver until they exhaust retries; no new deliveries fire.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    async deleteWebhook(workspaceId: string, webhookId: string): Promise<void> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!webhookId) throw new Error('webhookId is required.');
+      return client._request<void>({
+        method: 'DELETE',
+        endpoint: `/v1/workspaces/${workspaceId}/webhooks/${webhookId}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Generate a new HMAC signing secret for a subscription and return
+     * it once. The old secret is invalidated immediately.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    async rotateWebhookSecret(
+      workspaceId: string,
+      webhookId: string,
+    ): Promise<RotateWebhookSecretResponse> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!webhookId) throw new Error('webhookId is required.');
+      return client._request<RotateWebhookSecretResponse>({
+        method: 'POST',
+        endpoint: `/v1/workspaces/${workspaceId}/webhooks/${webhookId}/rotate-secret`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Fire a synthetic `webhook.test` delivery to the subscription's
+     * URL. The receiver gets a small payload they can use to verify
+     * their HMAC + parsing setup. Returns immediately; check the
+     * delivery log for the outcome.
+     */
+    async testWebhook(workspaceId: string, webhookId: string): Promise<TestWebhookResponse> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!webhookId) throw new Error('webhookId is required.');
+      return client._request<TestWebhookResponse>({
+        method: 'POST',
+        endpoint: `/v1/workspaces/${workspaceId}/webhooks/${webhookId}/test`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Paginated list of delivery attempts for a webhook subscription.
+     * Useful for diagnosing failures (HTTP status, response body snippet,
+     * retry timing).
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    async listWebhookDeliveries(
+      workspaceId: string,
+      webhookId: string,
+      params: ListDeliveriesParams = {},
+    ): Promise<ListDeliveriesResponse> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!webhookId) throw new Error('webhookId is required.');
+      const search = new URLSearchParams();
+      if (params.limit !== undefined) search.set('limit', String(params.limit));
+      if (params.cursor !== undefined) search.set('cursor', params.cursor);
+      if (params.status !== undefined) search.set('status', params.status);
+      const qs = search.toString();
+      return client._request<ListDeliveriesResponse>({
+        method: 'GET',
+        endpoint: `/v1/workspaces/${workspaceId}/webhooks/${webhookId}/deliveries${qs ? `?${qs}` : ''}`,
+        sendJWT: true,
+        bypassCache: true,
+      });
+    },
+
+    /**
+     * Re-fire a specific past delivery attempt. Useful for confirming a
+     * receiver fix without waiting for the next real event.
+     *
+     * @requires `canManageWebhooks` on the workspace.
+     */
+    async replayWebhookDelivery(
+      workspaceId: string,
+      webhookId: string,
+      attemptId: string,
+    ): Promise<{ attempt: WebhookAttempt }> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!webhookId) throw new Error('webhookId is required.');
+      if (!attemptId) throw new Error('attemptId is required.');
+      return client._request<{ attempt: WebhookAttempt }>({
+        method: 'POST',
+        endpoint: `/v1/workspaces/${workspaceId}/webhooks/${webhookId}/deliveries/${attemptId}/replay`,
+        sendJWT: true,
+      });
+    },
+  };
+}