@nurama/sdk 0.0.0-stage → 1.4.1

package/src/routes/device.ts

@@ -0,0 +1,133 @@
+import NuramaClient from '../NuramaClient.js';
+import {
+  type Device,
+  type RegisterDeviceBody,
+  type UpdateDeviceBody,
+  type GetUserDevicesQuery,
+} from '@nurama/types';
+
+/**
+ * Defines device-related methods for the NuramaClient.
+ * Handles device registration and management for push notifications.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the device-related methods.
+ */
+export default function createDeviceMethods(client: NuramaClient) {
+  return {
+    /**
+     * Register a new device for push notifications.
+     * If the same push token is registered again, the existing device will be updated.
+     * Requires authentication.
+     * @param {RegisterDeviceBody} deviceData - Device registration data.
+     * @returns {Promise<Device>} The registered device object.
+     * @example
+     * const device = await client.device.registerDevice({
+     *   deviceType: 'ios',
+     *   pushToken: 'ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]',
+     *   bundleId: 'com.nurama.mobile',
+     *   deviceInfo: {
+     *     appVersion: '1.0.0',
+     *     osVersion: '17.0',
+     *     deviceModel: 'iPhone 15',
+     *     deviceName: "John's iPhone"
+     *   }
+     * });
+     */
+    async registerDevice(deviceData: RegisterDeviceBody): Promise<Device> {
+      if (!deviceData.deviceType || !deviceData.pushToken) {
+        throw new Error('deviceType and pushToken are required.');
+      }
+      return client._request<Device>({
+        method: 'POST',
+        endpoint: '/v1/devices',
+        body: deviceData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Get all devices for the authenticated user.
+     * Requires authentication.
+     * @param {GetUserDevicesQuery} [filters] - Optional filters (status, deviceType).
+     * @returns {Promise<Device[]>} Array of device objects.
+     * @example
+     * const devices = await client.device.getUserDevices({ status: 'active' });
+     */
+    async getUserDevices(filters?: GetUserDevicesQuery): Promise<Device[]> {
+      return client._request<Device[]>({
+        method: 'GET',
+        endpoint: '/v1/devices',
+        params: filters,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Get a specific device by ID.
+     * Users can only access their own devices.
+     * Requires authentication.
+     * @param {string} deviceId - The device ID.
+     * @returns {Promise<Device>} The device object.
+     * @example
+     * const device = await client.device.getDevice('507f1f77bcf86cd799439011');
+     */
+    async getDevice(deviceId: string): Promise<Device> {
+      if (!deviceId) {
+        throw new Error('deviceId is required.');
+      }
+      return client._request<Device>({
+        method: 'GET',
+        endpoint: `/v1/devices/${deviceId}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Update device information.
+     * Users can only update their own devices.
+     * Requires authentication.
+     * @param {string} deviceId - The device ID.
+     * @param {UpdateDeviceBody} updateData - Data to update (pushToken, deviceInfo, status, subscribedChannels).
+     * @returns {Promise<Device>} The updated device object.
+     * @example
+     * const device = await client.device.updateDevice('507f1f77bcf86cd799439011', {
+     *   deviceInfo: { appVersion: '1.1.0' },
+     *   status: 'active'
+     * });
+     */
+    async updateDevice(deviceId: string, updateData: UpdateDeviceBody): Promise<Device> {
+      if (!deviceId) {
+        throw new Error('deviceId is required.');
+      }
+      if (Object.keys(updateData).length === 0) {
+        throw new Error('At least one field must be provided to update the device.');
+      }
+      return client._request<Device>({
+        method: 'PUT',
+        endpoint: `/v1/devices/${deviceId}`,
+        body: updateData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Delete a device.
+     * Users can only delete their own devices.
+     * Requires authentication.
+     * @param {string} deviceId - The device ID.
+     * @returns {Promise<void>}
+     * @example
+     * await client.device.deleteDevice('507f1f77bcf86cd799439011');
+     */
+    async deleteDevice(deviceId: string): Promise<void> {
+      if (!deviceId) {
+        throw new Error('deviceId is required.');
+      }
+      return client._request<void>({
+        method: 'DELETE',
+        endpoint: `/v1/devices/${deviceId}`,
+        sendJWT: true,
+      });
+    },
+  };
+}

package/src/routes/folder.ts

@@ -0,0 +1,154 @@
+import NuramaClient from '../NuramaClient.js';
+import {
+  type Folder,
+  type Asset,
+  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 (Consider moving to a shared file if used elsewhere) ---
+export interface PaginationParams {
+    limit?: number;
+    page?: number;
+}
+
+export interface SortParams {
+    sort?: Record<string, 1 | -1>;
+}
+
+// --- Request Body Interfaces ---
+export interface UpdateFolderData {
+    name?: string;
+    color?: string;
+}
+
+export interface UpdateFolderIconData {
+    name: string;
+    checksum: string;
+    sizeInMB: number;
+}
+
+
+
+export interface TagFolderData {
+    tagId: string;
+}
+
+export interface UntagFolderData {
+    tagId: string;
+}
+
+// --- Query Parameter Interfaces ---
+export interface GetFoldersAssetsParams extends PaginationParams, SortParams {
+    visibility?: 'creator' | 'reviewer';
+    chats?: boolean;
+    messages?: number;
+    replies?: number;
+}
+
+// --- Response Interfaces ---
+export type FolderResponse = Folder; // Use Folder type
+export type AssetResponse = Asset; // Use Asset type
+
+/**
+ * Defines folder-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the folder-related methods.
+ */
+export default function createFolderMethods(client: NuramaClient) {
+  return {
+    /** Fetch a single folder by id. */
+    async getFolder(folderId: string): Promise<FolderResponse> {
+      if (!folderId) throw new Error('folderId is required.');
+      return client._request<FolderResponse>({
+        method: 'GET',
+        endpoint: `/v1/folders/${folderId}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Updates a folder's name and/or color.
+     * @param {string} folderId - The ID of the folder to update.
+     * @param {UpdateFolderData} data - Data containing the name and/or color to update.
+     * @returns {Promise<FolderResponse>} The updated folder object.
+     */
+    async updateFolder(folderId: string, data: UpdateFolderData): Promise<FolderResponse> {
+      if (!folderId) throw new Error('folderId is required.');
+      return client._request<FolderResponse>({
+        method: 'PUT',
+        endpoint: `/v1/folders/${folderId}`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Updates a folder's icon.
+     * @param {string} folderId - The ID of the folder to update.
+     * @param {UpdateFolderIconData} data - Icon file data including name, checksum, and size.
+     * @returns {Promise<any>} Object containing the updated folder and signed upload URLs.
+     */
+    async updateFolderIcon(folderId: string, data: UpdateFolderIconData): Promise<any> {
+      if (!folderId) throw new Error('folderId is required.');
+      return client._request<any>({
+        method: 'PUT',
+        endpoint: `/v1/folders/${folderId}/icon`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /** List the assets that live directly inside a folder (does not recurse). */
+    async getFoldersAssets(folderId: string, params?: GetFoldersAssetsParams): Promise<PaginatedResponse<AssetResponse>> {
+      if (!folderId) throw new Error('folderId is required.');
+      return client._request<PaginatedResponse<AssetResponse>>({
+        method: 'GET',
+        endpoint: `/v1/folders/${folderId}/assets`,
+        params: params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Tags a folder with a specific tag.
+     * @param {string} folderId - The ID of the folder to tag.
+     * @param {TagFolderData} tagData - Data containing the tag ID.
+     * @returns {Promise<FolderResponse>} The updated folder object.
+     */
+    async tagFolder(folderId: string, tagData: TagFolderData): Promise<FolderResponse> {
+      if (!folderId) throw new Error('folderId is required.');
+      if (!tagData.tagId) throw new Error('tagId is required.');
+      return client._request<FolderResponse>({
+        method: 'PUT',
+        endpoint: `/v1/folders/${folderId}/tag`,
+        body: tagData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Untags a folder by removing a specific tag.
+     * @param {string} folderId - The ID of the folder to untag.
+     * @param {UntagFolderData} untagData - Data containing the tag ID to remove.
+     * @returns {Promise<FolderResponse>} The updated folder object.
+     */
+    async untagFolder(folderId: string, untagData: UntagFolderData): Promise<FolderResponse> {
+      if (!folderId) throw new Error('folderId is required.');
+      if (!untagData.tagId) throw new Error('tagId is required.');
+      return client._request<FolderResponse>({
+        method: 'PUT',
+        endpoint: `/v1/folders/${folderId}/untag`,
+        body: untagData,
+        sendJWT: true,
+      });
+    },
+
+  };
+}

package/src/routes/invite.ts

@@ -0,0 +1,133 @@
+import NuramaClient from '../NuramaClient.js';
+import {
+  type Invite,
+  type Membership,
+  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[];
+};
+
+// --- Request Body Interfaces ---
+export interface InviteUserToResourceData {
+    inviteeEmail: string;
+    resourceType: string; // e.g., 'workspace', 'project'
+    resourceId: string;
+    role: string; // Use a specific type/enum if possible based on `invitableRoles`
+    /** Optional workspace-level roles granted alongside the primary role
+     *  (subset of the backend `additionalRoles`, e.g. workspaceChatMember,
+     *  workspaceAdmin). Applied to the workspace membership on accept. */
+    additionalRoles?: string[];
+}
+
+// --- Query Parameter Interfaces ---
+export type InviteStatus = 'active' | 'canceled' | 'accepted';
+
+export interface GetUsersInvitesParams {
+    inviteType?: 'all' | 'inviter' | 'invitee';
+    status?: InviteStatus | InviteStatus[];
+}
+
+export interface GetInvitesToResourceParams {
+    status?: InviteStatus | InviteStatus[];
+}
+
+// --- Response Interfaces ---
+export type InviteResponse = Invite;
+// Assuming the response for getInvites might be complex depending on params
+export type PaginatedInvitesResponse = PaginatedResponse<Invite> | { inviter: Invite[], invitee: Invite[] } | Invite[]; 
+export type AcceptInviteResponse = {
+    membership: Membership; // Use Membership type
+    invite: Invite; // Use Invite type
+};
+
+/**
+ * Defines invite-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the invite-related methods.
+ */
+export default function createInviteMethods(client: NuramaClient) {
+  return {
+    /**
+     * Invite a user (by email) to a workspace or project at a given role.
+     * Triggers an invitation email; the recipient accepts via the link.
+     */
+    async inviteUser(data: InviteUserToResourceData): Promise<InviteResponse> {
+      return client._request<InviteResponse>({
+        method: 'POST',
+        endpoint: '/v1/invites',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /** List invites the current user has issued (pending, accepted, expired). */
+    async getInvites(params?: GetUsersInvitesParams): Promise<PaginatedInvitesResponse> {
+      return client._request<PaginatedInvitesResponse>({
+        method: 'GET',
+        endpoint: '/v1/invites',
+        params: params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Look up an invite by id. Public — no auth — so the recipient can
+     * preview the invite (target resource, role, inviter) before signing
+     * up or logging in.
+     */
+    async getInviteById(inviteId: string): Promise<InviteResponse> {
+      if (!inviteId) throw new Error('inviteId is required.');
+      return client._request<InviteResponse>({
+        method: 'GET',
+        endpoint: `/v1/invites/${inviteId}`,
+        sendJWT: false, // Public route - no authentication required
+      });
+    },
+
+    /** Revoke a pending invite. */
+    async cancelInvite(inviteId: string): Promise<InviteResponse> {
+      if (!inviteId) throw new Error('inviteId is required.');
+      return client._request<InviteResponse>({
+        method: 'DELETE',
+        endpoint: `/v1/invites/${inviteId}`,
+        sendJWT: true,
+      });
+    },
+
+    /** List pending invites attached to a workspace or project resource. */
+    async getInvitesForResource(resourceId: string, params?: GetInvitesToResourceParams): Promise<InviteResponse[]> {
+      if (!resourceId) throw new Error('resourceId is required.');
+      return client._request<InviteResponse[]>({
+        method: 'GET',
+        endpoint: `/v1/invites/resource/${resourceId}`,
+        params: params,
+        sendJWT: true,
+      });
+    },
+
+    /** Accept an invite for the authenticated user. Creates the membership. */
+    async acceptInvite(inviteId: string): Promise<AcceptInviteResponse> {
+      if (!inviteId) throw new Error('inviteId is required.');
+      return client._request<AcceptInviteResponse>({
+        method: 'POST',
+        endpoint: `/v1/invites/accept/${inviteId}`,
+        sendJWT: true,
+      });
+    },
+
+    /** Re-send a pending invite email (does not extend or reissue the token). */
+    async resendInvite(inviteId: string): Promise<InviteResponse> {
+      if (!inviteId) throw new Error('inviteId is required.');
+      return client._request<InviteResponse>({
+        method: 'POST',
+        endpoint: `/v1/invites/resend/${inviteId}`,
+        sendJWT: true,
+      });
+    },
+  };
+} 

package/src/routes/joinLink.ts

@@ -0,0 +1,233 @@
+import NuramaClient from '../NuramaClient.js';
+import {
+  type JoinLink,
+  type JoinLinkPreview,
+  type CreateJoinLinkPayload,
+  type UpdateJoinLinkPayload,
+  type RedeemJoinLinkResult,
+  type ListJoinRequestsResponse,
+  type ListMyJoinRequestsResponse,
+  type ApproveJoinRequestResponse,
+  type RejectJoinRequestRequest,
+  type RejectJoinRequestResponse,
+  type UpdateJoinRequestCooldownRequest,
+  type ProjectJoinRequest,
+  type ListBansResponse,
+  type CreateResourceBanRequest,
+  type ResourceBan,
+} from '@nurama/types';
+
+// --- Query Parameter Interfaces ---
+export interface GetJoinLinksParams {
+  projectId: string;
+}
+
+// --- Response Interfaces ---
+export type JoinLinkResponse = JoinLink;
+export interface JoinLinksListResponse {
+  results: JoinLink[];
+}
+
+/**
+ * Defines join-link ("invite link") methods for the NuramaClient. A join link
+ * lets people join a project via a shareable URL; management is gated by the
+ * caller's grant authority and the workspace plan's per-mode capability
+ * (enforced server-side).
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the join-link methods.
+ */
+export default function createJoinLinkMethods(client: NuramaClient) {
+  return {
+    /** Create a join link for a project. */
+    async createJoinLink(data: CreateJoinLinkPayload): Promise<JoinLinkResponse> {
+      return client._request<JoinLinkResponse>({
+        method: 'POST',
+        endpoint: '/v1/join-links',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /** List a project's join links. */
+    async getJoinLinks(params: GetJoinLinksParams): Promise<JoinLinksListResponse> {
+      if (!params?.projectId) throw new Error('projectId is required.');
+      return client._request<JoinLinksListResponse>({
+        method: 'GET',
+        endpoint: '/v1/join-links',
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /** The queue of people waiting on a decision for this project. */
+    async getJoinRequests(params: { projectId: string }): Promise<ListJoinRequestsResponse> {
+      if (!params?.projectId) throw new Error('projectId is required.');
+      return client._request<ListJoinRequestsResponse>({
+        method: 'GET',
+        endpoint: '/v1/join-links/requests',
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * The caller's own requests still waiting on a decision.
+     *
+     * Needs no `projectId`: it is scoped server-side to the caller, who is not
+     * a member of the projects they are waiting on and so cannot read those
+     * projects' queues.
+     */
+    async getMyJoinRequests(): Promise<ListMyJoinRequestsResponse> {
+      return client._request<ListMyJoinRequestsResponse>({
+        method: 'GET',
+        endpoint: '/v1/join-links/requests/mine',
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Approve a request and admit the person.
+     *
+     * Seats and the link's remaining uses are re-checked here, not when the
+     * request was made — a queue outlives the capacity that existed when it was
+     * filled, so approval can legitimately fail on a seat limit.
+     */
+    async approveJoinRequest(requestId: string, projectId: string): Promise<ApproveJoinRequestResponse> {
+      if (!requestId) throw new Error('requestId is required.');
+      if (!projectId) throw new Error('projectId is required.');
+      return client._request<ApproveJoinRequestResponse>({
+        method: 'POST',
+        endpoint: `/v1/join-links/requests/${requestId}/approve`,
+        body: { projectId },
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Reject a request, optionally barring the person.
+     *
+     * Passing `ban` is destructive beyond the refusal: a ban REMOVES an existing
+     * membership, so it can take away access the person already had in scope.
+     * It is a separate field for that reason, never implied by the rejection.
+     */
+    async rejectJoinRequest(requestId: string, data: RejectJoinRequestRequest): Promise<RejectJoinRequestResponse> {
+      if (!requestId) throw new Error('requestId is required.');
+      if (!data?.projectId) throw new Error('projectId is required.');
+      return client._request<RejectJoinRequestResponse>({
+        method: 'POST',
+        endpoint: `/v1/join-links/requests/${requestId}/reject`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Change or lift the cooldown on a rejected request.
+     *
+     * Only a rejected request has one; `reapplyAfter: null` lifts it, letting
+     * the person ask again straight away. A barred person is refused — the ban
+     * already blocks every path, so lifting that is the action that matters.
+     */
+    async updateJoinRequestCooldown(
+      requestId: string,
+      data: UpdateJoinRequestCooldownRequest,
+    ): Promise<ProjectJoinRequest> {
+      if (!requestId) throw new Error('requestId is required.');
+      if (!data?.projectId) throw new Error('projectId is required.');
+      return client._request<ProjectJoinRequest>({
+        method: 'PATCH',
+        endpoint: `/v1/join-links/requests/${requestId}/cooldown`,
+        body: { projectId: data.projectId, reapplyAfter: data.reapplyAfter ?? null },
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Bar someone, without a request to refuse.
+     *
+     * Destructive: the ban REMOVES every membership the person holds in its
+     * scope, so a `workspace` ban clears them out of every project in it. An
+     * owner cannot be barred, and neither can you bar yourself.
+     */
+    async createResourceBan(data: CreateResourceBanRequest): Promise<ResourceBan> {
+      if (!data?.projectId) throw new Error('projectId is required.');
+      if (!data?.userId) throw new Error('userId is required.');
+      if (!data?.scope) throw new Error('scope is required.');
+      return client._request<ResourceBan>({
+        method: 'POST',
+        endpoint: '/v1/join-links/bans',
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /** People barred from this project, newest first. */
+    async getResourceBans(params: { projectId: string }): Promise<ListBansResponse> {
+      if (!params?.projectId) throw new Error('projectId is required.');
+      return client._request<ListBansResponse>({
+        method: 'GET',
+        endpoint: '/v1/join-links/bans',
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /** Lift a ban. It does not restore any membership the ban removed. */
+    async liftResourceBan(banId: string): Promise<ResourceBan> {
+      if (!banId) throw new Error('banId is required.');
+      return client._request<ResourceBan>({
+        method: 'DELETE',
+        endpoint: `/v1/join-links/bans/${banId}`,
+        sendJWT: true,
+      });
+    },
+
+    /** Update a join link's settings (role, mode, domains, expiry, enable/disable). */
+    async updateJoinLink(linkId: string, data: UpdateJoinLinkPayload): Promise<JoinLinkResponse> {
+      if (!linkId) throw new Error('linkId is required.');
+      return client._request<JoinLinkResponse>({
+        method: 'PATCH',
+        endpoint: `/v1/join-links/${linkId}`,
+        body: data,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Rotate a link's token, invalidating the old URL. Optionally reset expiry.
+     * Existing memberships are untouched.
+     */
+    async rollJoinLink(linkId: string, expiresAt?: string | null): Promise<JoinLinkResponse> {
+      if (!linkId) throw new Error('linkId is required.');
+      return client._request<JoinLinkResponse>({
+        method: 'POST',
+        endpoint: `/v1/join-links/${linkId}/roll`,
+        body: expiresAt !== undefined ? { expiresAt } : {},
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Public preview of a join link by token — no auth — so the join landing
+     * page can show "Join <project>" before the visitor signs in.
+     */
+    async getJoinByToken(token: string): Promise<JoinLinkPreview> {
+      if (!token) throw new Error('token is required.');
+      return client._request<JoinLinkPreview>({
+        method: 'GET',
+        endpoint: `/v1/join/${token}`,
+        sendJWT: false, // Public route - no authentication required
+      });
+    },
+
+    /** Redeem a join link for the authenticated user. */
+    async joinByToken(token: string): Promise<RedeemJoinLinkResult> {
+      if (!token) throw new Error('token is required.');
+      return client._request<RedeemJoinLinkResult>({
+        method: 'POST',
+        endpoint: `/v1/join/${token}`,
+        sendJWT: true,
+      });
+    },
+  };
+}