@nurama/sdk 0.0.0-stage → 1.4.1

package/src/routes/membership.ts

@@ -0,0 +1,237 @@
+import NuramaClient from '../NuramaClient.js';
+import {
+  type Membership,
+  type MembershipReport,
+  type Mentionable,
+} from '@nurama/types';
+
+// --- Common Interfaces (Should be shared) ---
+export interface PaginationParams {
+    limit?: number;
+    page?: number;
+}
+
+export interface SortParams {
+    sort?: Record<string, 1 | -1>;
+}
+
+// --- Request Body Interfaces ---
+export interface AddRemoveRoleData {
+    membershipId: string;
+    role: string; // Consider using a type/enum based on invitableRoles
+}
+
+// --- Query Parameter Interfaces ---
+export interface GetWorkspaceMembershipParams extends PaginationParams, SortParams {
+    nameSearch?: string | null;
+    isBillable?: boolean;
+}
+
+export interface GetProjectMembershipParams extends PaginationParams, SortParams {
+    nameSearch?: string | null;
+}
+
+// --- Last Seen Interfaces ---
+export interface GetLastSeenData {
+    userIds: string[];
+}
+
+export interface LastSeenResult {
+    userId: string;
+    resourceId: string;
+    resourceType: 'workspace' | 'project';
+    lastSeen: string | null;
+}
+
+export interface GetLastSeenResponse {
+    results: LastSeenResult[];
+}
+
+// --- Response Interfaces ---
+export type MembershipResponse = Membership; // Use Membership type for single responses
+export type PaginatedMembershipResponse = MembershipReport; // Use MembershipReport for paginated results
+export type MentionableUserResponse = Mentionable; // Use Mentionable type
+
+/**
+ * Defines membership-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the membership-related methods.
+ */
+export default function createMembershipMethods(client: NuramaClient) {
+  return {
+    /**
+         * Retrieves the membership records for the currently authenticated user.
+         * @returns {Promise<MembershipResponse[]>} An array of the user's membership records.
+         */
+    async getMyMemberships(): Promise<MembershipResponse[]> {
+      return client._request<MembershipResponse[]>({
+        method: 'GET',
+        endpoint: '/v1/memberships/',
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves memberships associated with a specific workspace.
+         * Requires permission to get workspace members.
+         * @param {string} workspaceId - The ID of the workspace.
+         * @param {GetWorkspaceMembershipParams} [params] - Query parameters for pagination, sorting, filtering.
+         * @returns {Promise<PaginatedMembershipResponse>} Paginated list of workspace memberships.
+         */
+    async getWorkspaceMemberships(workspaceId: string, params?: GetWorkspaceMembershipParams): Promise<PaginatedMembershipResponse> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request<PaginatedMembershipResponse>({
+        method: 'GET',
+        endpoint: `/v1/memberships/workspace/${workspaceId}`,
+        params: params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves memberships associated with a specific project.
+         * Requires permission based on user's role in the project/workspace.
+         * @param {string} projectId - The ID of the project.
+         * @param {GetProjectMembershipParams} [params] - Query parameters for pagination, sorting, filtering.
+         * @returns {Promise<PaginatedMembershipResponse>} Paginated list of project memberships.
+         */
+    async getProjectMemberships(projectId: string, params?: GetProjectMembershipParams): Promise<PaginatedMembershipResponse> {
+      if (!projectId) throw new Error('projectId is required.');
+      return client._request<PaginatedMembershipResponse>({
+        method: 'GET',
+        endpoint: `/v1/memberships/project/${projectId}`,
+        params: params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Deletes a specific membership record by its ID.
+         * Requires specific permissions to delete others' memberships.
+         * @param {string} membershipId - The ID of the membership record to delete.
+         * @returns {Promise<void>} 
+         */
+    async deleteMembership(membershipId: string): Promise<void> {
+      if (!membershipId) throw new Error('membershipId is required.');
+      return client._request({
+        method: 'DELETE',
+        endpoint: `/v1/memberships/${membershipId}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Allows the authenticated user to leave a resource (delete their own membership).
+         * Cannot be used to remove ownership roles.
+         * @param {string} resourceId - The ID of the resource (workspace or project) to leave.
+         * @returns {Promise<void>} 
+         */
+    async leaveResource(resourceId: string): Promise<void> {
+      if (!resourceId) throw new Error('resourceId is required.');
+      return client._request({
+        method: 'DELETE',
+        endpoint: `/v1/memberships/leave/${resourceId}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Adds a role to an existing membership record.
+         * Requires permission to add roles.
+         * @param {AddRemoveRoleData} data - Object containing membershipId and the role to add.
+         * @returns {Promise<MembershipResponse>} The updated membership object.
+         */
+    async addRole(data: AddRemoveRoleData): Promise<MembershipResponse> {
+      if (!data || !data.membershipId || !data.role) {
+        throw new Error('membershipId and role are required.');
+      }
+      return client._request<MembershipResponse>({
+        method: 'POST',
+        endpoint: '/v1/memberships/add-role',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Removes a role from an existing membership record.
+         * Requires permission to remove roles. Cannot remove ownership roles.
+         * @param {AddRemoveRoleData} data - Object containing membershipId and the role to remove.
+         * @returns {Promise<MembershipResponse>} The updated membership object.
+         */
+    async removeRole(data: AddRemoveRoleData): Promise<MembershipResponse> {
+      if (!data || !data.membershipId || !data.role) {
+        throw new Error('membershipId and role are required.');
+      }
+      return client._request<MembershipResponse>({
+        method: 'POST',
+        endpoint: '/v1/memberships/remove-role',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves a list of users mentionable within a project based on visibility.
+         * Requires permission to get mentionable users.
+         * @param {string} projectId - The ID of the project.
+         * @param {'creator' | 'reviewer' | 'all'} visibility - The visibility scope. Pass 'all' to get users from both creator and reviewer visibilities (e.g. for boards visible to both).
+         * @returns {Promise<MentionableUserResponse[]>} An array of mentionable user objects.
+         */
+    async getProjectMentionableUsers(projectId: string, visibility: 'creator' | 'reviewer' | 'all'): Promise<MentionableUserResponse[]> {
+      if (!projectId) throw new Error('projectId is required.');
+      if (!visibility) throw new Error('visibility is required.');
+      return client._request<MentionableUserResponse[]>({
+        method: 'GET',
+        endpoint: `/v1/memberships/mentionable/project/${projectId}/${visibility}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves resource-specific last seen timestamps for multiple users in a workspace.
+         * Requires permission to get workspace members.
+         * @param {string} workspaceId - The ID of the workspace.
+         * @param {GetLastSeenData} data - Object containing array of user IDs (1-100).
+         * @returns {Promise<GetLastSeenResponse>} Object with results array containing last seen data.
+         */
+    async getWorkspaceLastSeen(workspaceId: string, data: GetLastSeenData): Promise<GetLastSeenResponse> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!data || !data.userIds || !Array.isArray(data.userIds) || data.userIds.length === 0) {
+        throw new Error('userIds array is required and must contain at least one user ID.');
+      }
+      if (data.userIds.length > 100) {
+        throw new Error('userIds array cannot contain more than 100 user IDs.');
+      }
+      return client._request<GetLastSeenResponse>({
+        method: 'POST',
+        endpoint: `/v1/memberships/workspace/${workspaceId}/last-seen`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves resource-specific last seen timestamps for multiple users in a project.
+         * Requires permission to get project members.
+         * @param {string} projectId - The ID of the project.
+         * @param {GetLastSeenData} data - Object containing array of user IDs (1-100).
+         * @returns {Promise<GetLastSeenResponse>} Object with results array containing last seen data.
+         */
+    async getProjectLastSeen(projectId: string, data: GetLastSeenData): Promise<GetLastSeenResponse> {
+      if (!projectId) throw new Error('projectId is required.');
+      if (!data || !data.userIds || !Array.isArray(data.userIds) || data.userIds.length === 0) {
+        throw new Error('userIds array is required and must contain at least one user ID.');
+      }
+      if (data.userIds.length > 100) {
+        throw new Error('userIds array cannot contain more than 100 user IDs.');
+      }
+      return client._request<GetLastSeenResponse>({
+        method: 'POST',
+        endpoint: `/v1/memberships/project/${projectId}/last-seen`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+  };
+} 

package/src/routes/notification.ts

@@ -0,0 +1,166 @@
+import NuramaClient from '../NuramaClient.js';
+import {
+  type Notification,
+  type PaginatedResult,
+  type CursorPaginatedResult,
+} from '@nurama/types';
+
+// Combine pagination metadata with a results array
+// (Should be defined centrally or imported if used across multiple route files)
+export type PaginatedResponse<T> = (PaginatedResult | CursorPaginatedResult) & {
+  results?: T[];
+};
+
+// --- Common Interfaces (Should be shared) ---
+export interface PaginationParams {
+    limit?: number;
+    // Cursor specific
+    cursor?: string;
+    paginateReverse?: boolean;
+    includeCounts?: boolean;
+    includeCursorRecord?: boolean;
+    startAt?: string; 
+    includeStartAtRecord?: boolean;
+    // Index specific
+    page?: number;
+}
+
+export interface SortParams {
+    sort?: Record<string, 1 | -1>;
+}
+
+// --- Request Body Interfaces ---
+export interface BaseNotificationParams {
+    channels: string[];
+    types?: string[]; // Consider using a specific type based on notificationTypes
+}
+
+export interface GetNotificationsData extends BaseNotificationParams, PaginationParams, SortParams {
+    paginate?: 'cursor' | 'index';
+    // Index specific pagination params from validation
+    createdAfter?: number; 
+    createdBefore?: number;
+}
+
+export interface GetNewNotificationsData extends BaseNotificationParams, PaginationParams {
+     paginate?: 'cursor' | 'index';
+    updateLastSeen?: boolean;
+}
+
+export interface GetNewNotificationCountData extends BaseNotificationParams {}
+
+export interface ChannelQuery {
+    channels: string[];
+    types?: string[];
+}
+
+export interface GetNewNotificationCountBulkData {
+    channelQueries: ChannelQuery[];
+}
+
+export interface GetUsersLastNotificationsSeenData extends BaseNotificationParams {}
+
+export interface UpdateUsersLastSeenData extends BaseNotificationParams {}
+
+// --- Response Interfaces (using 'any' for now) ---
+ 
+//type NotificationResponse = any;
+export type PaginatedNotificationResponse = PaginatedResponse<Notification>;
+export type NotificationCountResponse = { count: number };
+export type NotificationCountBulkResponse = ({ channels: string[], types?: string[], count: number })[];
+export type LastSeenResponse = { channels: string[], lastSeen: number, types?: string[] }; // Defined based on comments/tests
+
+
+/**
+ * Defines notification-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the notification-related methods.
+ */
+export default function createNotificationMethods(client: NuramaClient) {
+  return {
+    /**
+         * Retrieves notifications for specified channels, with optional filtering and pagination.
+         * @param {GetNotificationsData} data - Request body containing channels, types, and pagination/sorting options.
+         * @returns {Promise<PaginatedNotificationResponse>} Paginated list of notifications.
+         */
+    async getNotifications(data: GetNotificationsData): Promise<PaginatedNotificationResponse> {
+      return client._request<PaginatedNotificationResponse>({
+        method: 'POST',
+        endpoint: '/v1/notifications/',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves new notifications since the user's last viewed timestamp for the specified channels.
+         * Optionally updates the last viewed timestamp.
+         * @param {GetNewNotificationsData} data - Request body containing channels, types, pagination, and update flag.
+         * @returns {Promise<PaginatedNotificationResponse>} Paginated list of new notifications.
+         */
+    async getNewNotifications(data: GetNewNotificationsData): Promise<PaginatedNotificationResponse> {
+      return client._request<PaginatedNotificationResponse>({
+        method: 'POST',
+        endpoint: '/v1/notifications/new',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Gets the count of new (unread) notifications for the specified channels.
+         * @param {GetNewNotificationCountData} data - Request body containing channels and optional types.
+         * @returns {Promise<NotificationCountResponse>} Object containing the count of new notifications.
+         */
+    async getNewNotificationCount(data: GetNewNotificationCountData): Promise<NotificationCountResponse> {
+      return client._request<NotificationCountResponse>({
+        method: 'POST',
+        endpoint: '/v1/notifications/count',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Gets the count of new notifications for multiple channel/type queries in a single request.
+         * @param {GetNewNotificationCountBulkData} data - Request body containing an array of channel queries.
+         * @returns {Promise<NotificationCountBulkResponse>} Array of objects, each containing channels, types (if provided), and count.
+         */
+    async getNewNotificationCountBulk(data: GetNewNotificationCountBulkData): Promise<NotificationCountBulkResponse> {
+      return client._request<NotificationCountBulkResponse>({
+        method: 'POST',
+        endpoint: '/v1/notifications/count/bulk',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves the last seen timestamp record for the specified channels and optional types.
+         * @param {GetUsersLastNotificationsSeenData} data - Request body containing channels and optional types.
+         * @returns {Promise<LastSeenResponse>} The last seen record object.
+         */
+    async getUsersLastNotificationsSeen(data: GetUsersLastNotificationsSeenData): Promise<LastSeenResponse> {
+      return client._request<LastSeenResponse>({
+        method: 'POST',
+        endpoint: '/v1/notifications/last-seen',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Updates (or creates) the last seen timestamp for the user for the specified channels and optional types.
+         * @param {UpdateUsersLastSeenData} data - Request body containing channels and optional types.
+         * @returns {Promise<LastSeenResponse>} The updated (or created) last seen record object.
+         */
+    async updateUsersLastSeen(data: UpdateUsersLastSeenData): Promise<LastSeenResponse> {
+      return client._request<LastSeenResponse>({
+        method: 'PUT',
+        endpoint: '/v1/notifications/last-seen',
+        body: data,
+        sendJWT: true,
+      });
+    },
+  };
+} 

package/src/routes/oauthGrant.ts

@@ -0,0 +1,64 @@
+import NuramaClient from '../NuramaClient.js';
+
+/**
+ * One application a user has authorised over OAuth.
+ *
+ * A grant is the record of consent: the scopes approved, and the tie binding
+ * every token issued under it. Revoking one withdraws the application's
+ * access.
+ */
+export interface OAuthGrantSummary {
+  /** Opaque identifier; pass to `revokeGrant`. */
+  grantId: string;
+  clientId: string | null;
+  /**
+   * The application's name.
+   *
+   * Chosen by the application itself when `verified` is false — treat it as
+   * display text from an untrusted source, never as identification.
+   */
+  clientName: string | null;
+  /**
+   * Whether Nurama configured this application.
+   *
+   * False for one that registered itself through Dynamic Client Registration:
+   * it picked its own name and nobody reviewed it.
+   */
+  verified: boolean;
+  /** Scopes the user approved, from the backend's token-scope registry. */
+  scopes: string[];
+  grantedAt: string;
+  expiresAt: string | null;
+}
+
+export default function createOAuthGrantMethods(client: NuramaClient) {
+  return {
+    /**
+     * List the applications the caller has authorised, newest first.
+     * Expired grants are omitted by the server.
+     */
+    async listGrants(): Promise<OAuthGrantSummary[]> {
+      const res = await client._request<{ results: OAuthGrantSummary[] }>({
+        method: 'GET',
+        endpoint: '/v1/oauth-grants',
+        sendJWT: true,
+        bypassCache: true,
+      });
+      return res.results;
+    },
+
+    /**
+     * Withdraw an application's access: the grant and every token issued
+     * under it. An access token already in flight stays valid until it
+     * expires, so revocation is not instantaneous for a request under way.
+     */
+    async revokeGrant(grantId: string): Promise<void> {
+      if (!grantId) throw new Error('grantId is required.');
+      return client._request<void>({
+        method: 'DELETE',
+        endpoint: `/v1/oauth-grants/${grantId}`,
+        sendJWT: true,
+      });
+    },
+  };
+}

package/src/routes/payment.ts

@@ -0,0 +1,104 @@
+import NuramaClient from '../NuramaClient.js';
+
+// --- Request Body Interfaces ---
+export interface StripeCheckoutRequest {
+  resourceId: string;
+  productId: string;
+  currency: 'usd' | 'gbp';
+  billingPeriod: 'month' | 'year';
+}
+
+export interface ManualCheckoutRequest {
+  resourceId: string;
+  productId: string;
+  currency: 'usd' | 'gbp';
+  billingPeriod: 'month' | 'year';
+}
+
+// --- Response Interfaces ---
+export interface StripeCheckoutResponse {
+  url: string;
+}
+
+export interface StripeCustomerResponse {
+  customerId: string;
+}
+
+export interface StripePortalResponse {
+  url: string;
+}
+
+/**
+ * Defines payment-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the payment-related methods.
+ */
+export default function createPaymentMethods(client: NuramaClient) {
+  return {
+    /**
+     * Create a Stripe subscription checkout session.
+     * Requires authentication and permission.
+     * @param {StripeCheckoutRequest} checkoutData - The checkout request data.
+     * @returns {Promise<StripeCheckoutResponse>} Object containing the Stripe checkout session URL.
+     */
+    async createStripeCheckout(checkoutData: StripeCheckoutRequest): Promise<StripeCheckoutResponse> {
+      if (!checkoutData.resourceId) throw new Error('resourceId is required.');
+      if (!checkoutData.productId) throw new Error('productId is required.');
+      if (!checkoutData.currency) throw new Error('currency is required.');
+      if (!checkoutData.billingPeriod) throw new Error('billingPeriod is required.');
+      
+      return client._request<StripeCheckoutResponse>({
+        method: 'POST',
+        endpoint: '/v1/payments/stripe/checkout',
+        body: checkoutData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Create a manual subscription without Stripe processing.
+     * Requires authentication and permission.
+     * @param {ManualCheckoutRequest} checkoutData - The manual checkout request data.
+     * @returns {Promise<any>} The created subscription object.
+     */
+    async createManualCheckout(checkoutData: ManualCheckoutRequest): Promise<any> {
+      if (!checkoutData.resourceId) throw new Error('resourceId is required.');
+      if (!checkoutData.productId) throw new Error('productId is required.');
+      if (!checkoutData.currency) throw new Error('currency is required.');
+      if (!checkoutData.billingPeriod) throw new Error('billingPeriod is required.');
+      
+      return client._request<any>({
+        method: 'POST',
+        endpoint: '/v1/payments/manual/checkout',
+        body: checkoutData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Create a new Stripe customer for the authenticated user.
+     * Requires authentication and permission.
+     * @returns {Promise<StripeCustomerResponse>} Object containing the Stripe customer ID.
+     */
+    async createStripeCustomer(): Promise<StripeCustomerResponse> {
+      return client._request<StripeCustomerResponse>({
+        method: 'POST',
+        endpoint: '/v1/payments/stripe/customer',
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Generate a URL for the Stripe customer portal for subscription management.
+     * Requires authentication and permission.
+     * @returns {Promise<StripePortalResponse>} Object containing the Stripe portal session URL.
+     */
+    async getStripePortalUrl(): Promise<StripePortalResponse> {
+      return client._request<StripePortalResponse>({
+        method: 'GET',
+        endpoint: '/v1/payments/stripe/portal',
+        sendJWT: true,
+      });
+    },
+  };
+}

package/src/routes/product.ts

@@ -0,0 +1,67 @@
+import NuramaClient from '../NuramaClient.js';
+import { type Product } from '@nurama/types'; // Import Product type
+
+// --- Query Parameter Interfaces ---
+export interface GetWorkspaceProductsParams {
+  productType?: 'basePlan' | 'addSeat' | 'addStorage' | 'addCredits' | 'enableBoards';
+  paymentProvider?: 'stripe' | 'manualInvoice';
+}
+
+// --- Response Interfaces ---
+export type ProductResponse = Product;
+
+/**
+ * Defines product-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the product-related methods.
+ */
+export default function createProductMethods(client: NuramaClient) {
+  return {
+    /**
+     * Retrieves available products for a specific workspace, considering restrictions.
+     * Requires authentication and permission.
+     * @param {string} workspaceId - The ID of the workspace.
+     * @param {GetWorkspaceProductsParams} [params] - Optional query parameters.
+     * @returns {Promise<ProductResponse[]>} An array of available product objects.
+     */
+    async getWorkspaceProducts(workspaceId: string, params?: GetWorkspaceProductsParams): Promise<ProductResponse[]> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request<ProductResponse[]>({
+        method: 'GET',
+        endpoint: `/v1/products/workspace/${workspaceId}`,
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * List active starter-package "plans" available to the caller,
+     * scoped by user-level restrictions but NOT bound to a workspace.
+     * Used by the post-signup plan-selection overlay before any
+     * workspace exists.
+     * @returns {Promise<ProductResponse[]>} Active starter-package plans.
+     */
+    async listPlans(): Promise<ProductResponse[]> {
+      return client._request<ProductResponse[]>({
+        method: 'GET',
+        endpoint: '/v1/products/plans',
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Suggested billing currency for the caller, derived server-side from
+     * the CDN geo header. A *default* for the currency selector only — the
+     * user can override. Falls back to `usd` with no geo header.
+     */
+    async getSuggestedCurrency(): Promise<{ currency: SupportedCurrency; country: string | null; locked?: boolean; supported: SupportedCurrency[] }> {
+      return client._request<{ currency: SupportedCurrency; country: string | null; supported: SupportedCurrency[] }>({
+        method: 'GET',
+        endpoint: '/v1/products/suggested-currency',
+        sendJWT: true,
+      });
+    },
+  };
+}
+
+export type SupportedCurrency = 'gbp' | 'usd' | 'eur';