@nurama/sdk 0.0.0-stage → 1.4.0

package/src/routes/storage.ts

@@ -0,0 +1,83 @@
+import NuramaClient from '../NuramaClient.js';
+
+// --- Resource Type Enum ---
+export type ResourceType = 'user' | 'workspace' | 'project' | 'chat' | 'asset';
+
+// --- Query Parameter Interfaces ---
+export interface GetStorageChartParams {
+    startDate?: number; // Unix timestamp (ms) or similar number format expected by backend
+    endDate?: number;   // Unix timestamp (ms) or similar number format expected by backend
+    aggregationPeriod?: 'year' | 'month' | 'week' | 'day';
+}
+
+// --- Response Interfaces ---
+export interface ChartDataEntry {
+    period: string; // e.g., "YYYY-MM-DD", "YYYY-W##", "YYYY-MM", "YYYY"
+    averageSizeInBytes: number;
+}
+
+export type ChartDataResponse = ChartDataEntry[];
+
+export interface StorageRecord {
+    resourceId: string;
+    resourceType: ResourceType;
+    sizeInBytes: number;
+    id: string; // The ID of the storage record itself
+}
+
+// --- Method Definitions ---
+
+/**
+ * Defines storage-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the storage-related methods.
+ */
+export default function createStorageMethods(client: NuramaClient) {
+  return {
+    /**
+         * Retrieves storage usage chart data for a specific resource.
+         * Requires authentication and permission.
+         * @param {ResourceType} resourceType - The type of the resource.
+         * @param {string} resourceId - The ID of the resource.
+         * @param {GetStorageChartParams} [params] - Optional query parameters for date range and aggregation.
+         * @returns {Promise<ChartDataResponse>} An array of chart data entries.
+         */
+    async getStorageChart(
+      resourceType: ResourceType,
+      resourceId: string,
+      params?: GetStorageChartParams
+    ): Promise<ChartDataResponse> {
+      if (!resourceType) throw new Error('resourceType is required.');
+      if (!resourceId) throw new Error('resourceId is required.');
+      return client._request<ChartDataResponse>({
+        method: 'GET',
+        endpoint: `/v1/storage/chart/${resourceType}/${resourceId}`,
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves the latest storage record for a specific resource.
+         * Requires authentication and permission.
+         * @param {ResourceType} resourceType - The type of the resource.
+         * @param {string} resourceId - The ID of the resource.
+         * @returns {Promise<StorageRecord>} The latest storage record for the resource.
+         */
+    async getStorageRecord(
+      resourceType: ResourceType,
+      resourceId: string
+    ): Promise<StorageRecord> {
+      if (!resourceType) throw new Error('resourceType is required.');
+      if (!resourceId) throw new Error('resourceId is required.');
+      return client._request<StorageRecord>({
+        method: 'GET',
+        endpoint: `/v1/storage/${resourceType}/${resourceId}`,
+        sendJWT: true,
+      });
+    },
+  };
+}
+
+// --- Export Method Type ---
+export type StorageMethods = ReturnType<typeof createStorageMethods>; 

package/src/routes/subscription.ts

@@ -0,0 +1,307 @@
+import NuramaClient from '../NuramaClient.js';
+import { type Subscription } from '@nurama/types'; // Import Subscription type
+
+// --- Common Interfaces (Should be shared) ---
+export interface SortParams {
+    sort?: Record<string, 1 | -1>;
+}
+
+export type SubscriptionStatus = 'active' | 'pending' | 'canceled' | 'expired' | 'pastDue' | 'paused' | 'paymentFailed' | 'unpaid';
+
+/**
+ * Soft warnings returned by a plan swap / dry-run. STRUCTURED (not localized
+ * strings) so the multi-lingual FE renders the copy from these values.
+ */
+export type PlanChangeWarning =
+  | { type: 'capabilityRemoved'; capability: string }
+  | {
+      type: 'seatMigration';
+      currentSeats: number;
+      unitPrice: number | null;
+      total: number | null;
+      currency: string;
+      period: 'month' | 'year';
+    };
+
+// --- Query Parameter Interfaces ---
+export interface GetSubscriptionsParams extends SortParams {
+    status?: SubscriptionStatus;
+    limit?: number;
+    page?: number;
+}
+
+export interface CreateWorkspaceOrderParams {
+    productId: string;
+    quantity: number;
+    /**
+     * Customer-chosen purchase amount in the subscription's currency MINOR
+     * unit (pence for GBP, cents for USD, yen for JPY, etc.). Required for
+     * variable-amount products (currently only the AI add-on, `productType:
+     * 'enableAi'`). Server enforces a per-currency minimum.
+     */
+    amountInMinor?: number;
+}
+
+export interface GetSubscriptionOrdersParams {
+    limit?: number;
+    page?: number;
+    sortBy?: string;
+}
+
+// --- Response Interfaces (based on YAML and tests) ---
+// Subscription type is imported from nurama-types
+
+// Keep local definitions for these as they are not in nurama-types
+export interface ResourceLimits {
+    totalStorageInBytes: number;
+    totalSeats: number;
+    totalCredits: number;
+}
+
+export interface SeatUsage {
+    totalSeats: number;
+    usedSeats: number;
+    availableSeats: number;
+}
+
+export interface RoleSeatUsage {
+    /** Distinct users occupying this seat type across the workspace + projects. */
+    used: number;
+    /** Plan cap for this seat type, or `null` when the plan is unlimited for it. */
+    limit: number | null;
+}
+
+export interface RoleUsage {
+    creators: RoleSeatUsage;
+    reviewers: RoleSeatUsage;
+}
+
+export interface StorageUsage {
+    totalStorageInBytes: number;
+    usedStorageInBytes: number;
+    availableStorageInBytes: number;
+}
+
+// --- Method Definitions ---
+
+/**
+ * Defines subscription-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the subscription-related methods.
+ */
+export default function createSubscriptionMethods(client: NuramaClient) {
+  return {
+    /**
+         * Retrieves the active subscription for a specific workspace.
+         * Requires authentication and permission.
+         * @param {string} workspaceId - The ID of the workspace.
+         * @returns {Promise<Subscription>} The workspace subscription object.
+         */
+    async getWorkspaceSubscription(workspaceId: string): Promise<Subscription> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request<Subscription>({
+        method: 'GET',
+        endpoint: `/v1/subscriptions/workspace/${workspaceId}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Cancels the subscription for a specific workspace.
+         * Requires authentication and permission.
+         * @param {string} workspaceId - The ID of the workspace.
+         * @returns {Promise<any>} The cancellation response.
+         */
+    async cancelWorkspaceSubscription(workspaceId: string): Promise<any> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request<any>({
+        method: 'DELETE',
+        endpoint: `/v1/subscriptions/workspace/${workspaceId}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Reverse a scheduled (period-end) cancellation, keeping the workspace's
+     * subscription on its normal renewal cycle. Only valid while the
+     * subscription is still active with a pending cancellation; a fully
+     * lapsed subscription can't be resumed (the owner must re-subscribe).
+     * Requires authentication and permission.
+     * @param {string} workspaceId - The ID of the workspace.
+     * @returns {Promise<any>} The resume response.
+     */
+    async resumeWorkspaceSubscription(workspaceId: string): Promise<any> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request<any>({
+        method: 'POST',
+        endpoint: `/v1/subscriptions/workspace/${workspaceId}/resume`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Swap the workspace's active basePlan line for a different basePlan product.
+     * Same code path both upgrades and downgrades; the API's pre-flight
+     * capacity check is what distinguishes a permitted change from a refused
+     * one. Pass `dryRun: true` to get the pre-flight verdict without mutating.
+     *
+     * On over-allocation the API returns 400 `planCapacityInsufficient` with
+     * `errorData.violations: [{ resource, current, newLimit }]`, surfaced via
+     * the SDK's normal error path.
+     *
+     * On success, returns the updated subscription plus a `warnings[]` array
+     * of feature-gate capabilities the destination plan does NOT include (the
+     * FE renders these as a confirmation notice).
+     */
+    async swapWorkspacePlan(workspaceId: string, params: {
+      newProductId: string;
+      currency: string;
+      billingPeriod: 'month' | 'year';
+      dryRun?: boolean;
+    }): Promise<{ subscription: Subscription | null; warnings: PlanChangeWarning[] }> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!params.newProductId) throw new Error('newProductId is required.');
+      if (!params.currency) throw new Error('currency is required.');
+      if (!params.billingPeriod) throw new Error('billingPeriod is required.');
+      return client._request<{ subscription: Subscription | null; warnings: PlanChangeWarning[] }>({
+        method: 'PUT',
+        endpoint: `/v1/subscriptions/workspace/${workspaceId}/plan`,
+        body: params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves subscription orders for a specific workspace.
+         * Requires authentication and permission.
+         * @param {string} workspaceId - The ID of the workspace.
+         * @param {GetSubscriptionOrdersParams} [params] - Optional query parameters.
+         * @returns {Promise<any[]>} An array of subscription order objects.
+         */
+    async getWorkspaceOrders(workspaceId: string, params?: GetSubscriptionOrdersParams): Promise<any[]> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request<any[]>({
+        method: 'GET',
+        endpoint: `/v1/subscriptions/workspace/${workspaceId}/orders`,
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Creates a subscription order for a specific workspace.
+         * Requires authentication and permission.
+         * @param {string} workspaceId - The ID of the workspace.
+         * @param {CreateWorkspaceOrderParams} orderData - The order data.
+         * @returns {Promise<any>} The created order response.
+         */
+    async createWorkspaceOrder(workspaceId: string, orderData: CreateWorkspaceOrderParams): Promise<any> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      if (!orderData.productId) throw new Error('productId is required.');
+      if (typeof orderData.quantity !== 'number') throw new Error('quantity is required and must be a number.');
+      
+      return client._request<any>({
+        method: 'POST',
+        endpoint: `/v1/subscriptions/workspace/${workspaceId}/order`,
+        body: orderData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves all subscriptions owned by the currently authenticated user.
+         * Requires authentication.
+         * @param {GetSubscriptionsParams} [params] - Optional query parameters for status and sorting.
+         * @returns {Promise<Subscription[]>} An array of subscription objects.
+         */
+    async getUserSubscriptions(params?: GetSubscriptionsParams): Promise<Subscription[]> {
+      return client._request<Subscription[]>({
+        method: 'GET',
+        endpoint: '/v1/subscriptions/',
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves the resource limits (e.g., storage, seats) for a specific resource (typically workspace).
+         * Requires authentication.
+         * @param {string} resourceId - The ID of the resource (e.g., workspaceId).
+         * @returns {Promise<ResourceLimits>} An object containing the resource limits.
+         */
+    async getResourceLimits(resourceId: string): Promise<ResourceLimits> {
+      if (!resourceId) throw new Error('resourceId is required.');
+      // Note: Backend route uses /limits/:resourceId, validation uses resourceId
+      // Endpoint in test file is not hit for limits directly, assuming workspace ID based on context
+      return client._request<ResourceLimits>({
+        method: 'GET',
+        endpoint: `/v1/subscriptions/limits/${resourceId}`, // Assuming resourceId here is workspaceId
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves the seat usage for a specific resource (typically workspace).
+         * Requires authentication.
+         * @param {string} resourceId - The ID of the resource (e.g., workspaceId).
+         * @returns {Promise<SeatUsage>} An object containing seat usage details.
+         */
+    async getSeatUsage(resourceId: string): Promise<SeatUsage> {
+      if (!resourceId) throw new Error('resourceId is required.');
+      return client._request<SeatUsage>({
+        method: 'GET',
+        endpoint: `/v1/subscriptions/usage/seats/${resourceId}`, // Assuming resourceId here is workspaceId
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves per-role (creator / reviewer) seat usage and caps for a
+         * workspace. `limit` is `null` when the plan is unlimited for that
+         * seat type. Requires authentication.
+         * @param {string} resourceId - The workspace ID.
+         * @returns {Promise<RoleUsage>} Creator- and reviewer-side seat usage.
+         */
+    async getRoleUsage(resourceId: string): Promise<RoleUsage> {
+      if (!resourceId) throw new Error('resourceId is required.');
+      return client._request<RoleUsage>({
+        method: 'GET',
+        endpoint: `/v1/subscriptions/usage/roles/${resourceId}`,
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves the storage usage for a specific resource (typically workspace).
+         * Requires authentication.
+         * @param {string} resourceId - The ID of the resource (e.g., workspaceId).
+         * @returns {Promise<StorageUsage>} An object containing storage usage details.
+         */
+    async getStorageUsage(resourceId: string): Promise<StorageUsage> {
+      if (!resourceId) throw new Error('resourceId is required.');
+      return client._request<StorageUsage>({
+        method: 'GET',
+        endpoint: `/v1/subscriptions/usage/storage/${resourceId}`, // Assuming resourceId here is workspaceId
+        sendJWT: true,
+      });
+    },
+
+    /**
+         * Retrieves the workspace usage summary (billable seats and storage used).
+         * Requires authentication and subscription management permission.
+         * @param {string} workspaceId - The ID of the workspace.
+         * @returns {Promise<{billableSeatCount: number; storageUsedInBytes: number}>} Usage summary.
+         */
+    async getWorkspaceUsageSummary(workspaceId: string): Promise<{
+      billableSeatCount: number;
+      storageUsedInBytes: number;
+    }> {
+      if (!workspaceId) throw new Error('workspaceId is required.');
+      return client._request({
+        method: 'GET',
+        endpoint: `/v1/subscriptions/workspace/${workspaceId}/usage-summary`,
+        sendJWT: true,
+      });
+    },
+  };
+} 

package/src/routes/supportChat.ts

@@ -0,0 +1,62 @@
+import NuramaClient from '../NuramaClient.js';
+import type {
+  SupportChatGetTopicResponse,
+  SupportChatCreateAttachmentRequest,
+  SupportChatCreateAttachmentResponse,
+} from '@nurama/types';
+
+/**
+ * Nurama Support chat — one topic per user on the `/news` page.
+ *
+ * The surface is intentionally tiny: one endpoint that lazily creates
+ * the user's support topic on first call and returns the existing row
+ * on every subsequent call. There is no list / archive / delete — each
+ * user has exactly one support conversation that persists across visits.
+ *
+ * Messages flow through the regular chat endpoints on
+ * `nuramaClient.chat`:
+ *
+ *   - send: `nuramaClient.chat.createMessage(topic.chatId, { content })`
+ *   - list: `nuramaClient.chat.getMessages(topic.chatId, …)`
+ *
+ * Backend gates: `auth → requireGlobalSupportChatEnabled → supportChatLimiter`.
+ * Unmetered (no credit deduction) — abuse is bounded by the per-user
+ * per-day rate limiter, not a credit balance check.
+ */
+export default function createSupportChatMethods(client: NuramaClient) {
+  return {
+    /**
+     * Get-or-create the caller's Support topic. Idempotent: re-calling
+     * returns the same row, so this is safe to invoke on every page mount.
+     */
+    async getTopic(): Promise<SupportChatGetTopicResponse> {
+      return client._request({
+        endpoint: '/v1/ai/support-chat/topic',
+        method: 'GET',
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Mint a Scratch upload bundle for one image attachment. The bytes
+     * land in a Scratch row with a 72-hour TTL and are read by the
+     * orchestrator's vision pass on the next user message — never
+     * promoted to a permanent Asset.
+     *
+     * Same upload protocol as every other multipart upload on the
+     * platform: call this, multipart-upload the bytes to `urls`, then
+     * call `nuramaClient.scratch.completeUpload(scratchId, { uploadId, parts })`.
+     * Send the message with `attachments: [{ scratchId, name }]`.
+     */
+    async createAttachment(
+      data: SupportChatCreateAttachmentRequest,
+    ): Promise<SupportChatCreateAttachmentResponse> {
+      return client._request({
+        endpoint: '/v1/ai/support-chat/attachments',
+        method: 'POST',
+        body: data,
+        sendJWT: true,
+      });
+    },
+  };
+}

package/src/routes/supportTicket.ts

@@ -0,0 +1,114 @@
+import NuramaClient from '../NuramaClient.js';
+
+export type SupportTicketScope = 'user' | 'workspace' | 'project';
+export type SupportTicketStatus = 'open' | 'pending' | 'resolved' | 'closed';
+
+export interface CreateSupportTicketRequest {
+  scopeType: SupportTicketScope;
+  /** Required for workspace/project scope; ignored for user scope. */
+  scopeId?: string;
+  subject: string;
+  body: string;
+  /** Browser/app/device snapshot collected at submit time. */
+  deviceInfo?: Record<string, unknown>;
+  /**
+   * `true` when the ticket was drafted by Nu via the
+   * `create_support_ticket` chat tool and submitted by the user from
+   * the pre-populated SupportTicketCreateModal. Stamped onto the
+   * `SupportTicket` row for ops analytics; the FE sets this when the
+   * modal was opened by an AI-draft CTA.
+   */
+  aiGenerated?: boolean;
+}
+
+export interface SupportTicket {
+  id: string;
+  ticketNumber: number;
+  subject: string;
+  scopeType: SupportTicketScope;
+  scopeId: string | null;
+  creatorId: string;
+  status: SupportTicketStatus;
+  priority: string;
+  chatId: string;
+  deviceInfo: Record<string, unknown>;
+  /** True for tickets drafted by Nu's `create_support_ticket` tool. */
+  aiGenerated: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface SupportTicketListParams {
+  status?: SupportTicketStatus;
+  page?: number;
+  limit?: number;
+}
+
+export interface SupportTicketListResponse {
+  results: SupportTicket[];
+  page: number;
+  limit: number;
+  totalPages: number;
+  totalResults: number;
+}
+
+/** A logo asset (thumbnail-ready) attached to a scope for avatar rendering. */
+export type SupportTicketScopeLogo = { files?: unknown[]; [key: string]: unknown } | null;
+
+export interface SupportTicketScopeOptions {
+  workspaces: { id: string; name: string; slug: string; color?: string | null; logo?: SupportTicketScopeLogo }[];
+  projects: { id: string; name: string; slug: string | null; workspaceId: string; color?: string | null; logo?: SupportTicketScopeLogo }[];
+}
+
+/**
+ * Support tickets. A ticket carries the metadata + a backing Chat thread; the
+ * conversation itself is sent/read through the regular chat endpoints:
+ *
+ *   - send: `nuramaClient.chat.createMessage(ticket.chatId, …)`
+ *   - read: `nuramaClient.chat.getMessages(ticket.chatId, …)`
+ *
+ * Nurama customer service replies (as the support persona) from the admin site.
+ */
+export default function createSupportTicketMethods(client: NuramaClient) {
+  const buildQuery = (params: Record<string, unknown> = {}): string => {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value === undefined || value === null || value === '') continue;
+      search.set(key, String(value));
+    }
+    const query = search.toString();
+    return query ? `?${query}` : '';
+  };
+
+  return {
+    /** Create a ticket. The opening message body becomes the first thread entry. */
+    async createSupportTicket(data: CreateSupportTicketRequest): Promise<SupportTicket> {
+      if (!data?.scopeType) throw new Error('scopeType is required.');
+      if (data.scopeType !== 'user' && !data.scopeId) {
+        throw new Error('scopeId is required for workspace/project scope.');
+      }
+      if (!data?.subject) throw new Error('subject is required.');
+      if (!data?.body) throw new Error('body is required.');
+      return client._request({ endpoint: '/v1/support-tickets', method: 'POST', body: data, sendJWT: true });
+    },
+
+    /** List the caller's own tickets + (for resource admins) tickets in their scope. */
+    async listSupportTickets(params: SupportTicketListParams = {}): Promise<SupportTicketListResponse> {
+      return client._request({ endpoint: `/v1/support-tickets${buildQuery(params as Record<string, unknown>)}`, method: 'GET', sendJWT: true });
+    },
+
+    async getSupportTicket(ticketId: string): Promise<SupportTicket> {
+      if (!ticketId) throw new Error('ticketId is required.');
+      return client._request({
+        endpoint: `/v1/support-tickets/${encodeURIComponent(ticketId)}`,
+        method: 'GET',
+        sendJWT: true,
+      });
+    },
+
+    /** Workspaces/projects the caller may scope a new ticket to. */
+    async getSupportTicketScopeOptions(): Promise<SupportTicketScopeOptions> {
+      return client._request({ endpoint: '/v1/support-tickets/scope-options', method: 'GET', sendJWT: true });
+    },
+  };
+}

package/src/routes/tag.ts

@@ -0,0 +1,131 @@
+import NuramaClient from '../NuramaClient.js';
+import { type Tag, type TagOwnerResourceType } from '@nurama/types';
+
+/**
+ * Data required to create a new tag
+ */
+export interface CreateTagData {
+  /** The name of the tag */
+  name: string;
+  
+  /** The type of resource that will own this tag */
+  ownerResourceType: TagOwnerResourceType;
+  
+  /** The ID of the resource that will own this tag */
+  ownerResourceId: string;
+  
+  /** Optional hex color code for the tag. If not provided, a color will be assigned automatically */
+  color?: string;
+}
+
+/**
+ * Data for updating an existing tag
+ */
+export interface UpdateTagData {
+  /** The new name for the tag */
+  name?: string;
+  
+  /** The new hex color code for the tag */
+  color?: string;
+}
+
+/**
+ * Parameters for getting tags for a resource
+ */
+export interface GetTagsParams {
+  /** Filter tags by partial name match (case-insensitive) */
+  name?: string;
+  
+  /** Sort tags by field */
+  sortBy?: 'name' | 'createdAt' | 'updatedAt';
+}
+
+/**
+ * Array of tags
+ */
+export type Tags = Tag[];
+
+/**
+ * Defines tag-related methods for the NuramaClient.
+ * @param {NuramaClient} client - The NuramaClient instance.
+ * @returns {object} An object containing the tag-related methods.
+ */
+export default function createTagMethods(client: NuramaClient) {
+  return {
+    /**
+     * Creates a new tag for a specific resource.
+     * @param {CreateTagData} tagData - The tag data to create.
+     * @returns {Promise<Tag>} The created tag object.
+     */
+    async createTag(tagData: CreateTagData): Promise<Tag> {
+      if (!tagData.name) throw new Error('Tag name is required.');
+      if (!tagData.ownerResourceType) throw new Error('Owner resource type is required.');
+      if (!tagData.ownerResourceId) throw new Error('Owner resource ID is required.');
+
+      return client._request<Tag>({
+        method: 'POST',
+        endpoint: '/v1/tags',
+        body: tagData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Retrieves all tags for a specific resource.
+     * @param {TagOwnerResourceType} ownerResourceType - The type of resource to get tags for.
+     * @param {string} ownerResourceId - The ID of the resource to get tags for.
+     * @param {GetTagsParams} [params] - Optional parameters for filtering and sorting.
+     * @returns {Promise<Tags>} Array of tag objects.
+     */
+    async getTags(
+      ownerResourceType: TagOwnerResourceType,
+      ownerResourceId: string,
+      params?: GetTagsParams
+    ): Promise<Tags> {
+      if (!ownerResourceType) throw new Error('Owner resource type is required.');
+      if (!ownerResourceId) throw new Error('Owner resource ID is required.');
+
+      return client._request<Tags>({
+        method: 'GET',
+        endpoint: `/v1/tags/${ownerResourceType}/${ownerResourceId}`,
+        params,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Updates an existing tag.
+     * @param {string} tagId - The ID of the tag to update.
+     * @param {UpdateTagData} updateData - The data to update.
+     * @returns {Promise<Tag>} The updated tag object.
+     */
+    async updateTag(tagId: string, updateData: UpdateTagData): Promise<Tag> {
+      if (!tagId) throw new Error('Tag ID is required.');
+      if (!updateData.name && !updateData.color) {
+        throw new Error('At least one field (name or color) must be provided for update.');
+      }
+
+      return client._request<Tag>({
+        method: 'PUT',
+        endpoint: `/v1/tags/${tagId}`,
+        body: updateData,
+        sendJWT: true,
+      });
+    },
+
+    /**
+     * Deletes a tag permanently.
+     * @param {string} tagId - The ID of the tag to delete.
+     * @returns {Promise<Tag>} The deleted tag object.
+     */
+    async deleteTag(tagId: string): Promise<Tag> {
+      if (!tagId) throw new Error('Tag ID is required.');
+
+      return client._request<Tag>({
+        method: 'DELETE',
+        endpoint: `/v1/tags/${tagId}`,
+        sendJWT: true,
+      });
+    },
+  };
+}