@miosa/sdk 1.0.0 → 1.1.0

package/src/resources/workspace-invites.ts

@@ -0,0 +1,188 @@
+/**
+ * Workspace Invites — email invite flow for workspace access.
+ *
+ * Sending an invite to an email that already belongs to a tenant member
+ * short-circuits to directly adding that user (returns `type: "added"`).
+ * Accepting a workspace invite for an unknown email auto-creates both a
+ * `tenant_members` and a `workspace_members` row atomically.
+ *
+ * Public endpoints (no auth):
+ *   GET  /workspace-invites/:token
+ *
+ * Authenticated endpoints:
+ *   POST   /workspaces/:id/invites
+ *   GET    /workspaces/:id/invites
+ *   DELETE /workspaces/:id/invites/:invite_id
+ *   POST   /workspace-invites/:token/accept
+ */
+
+import type { HttpClient } from "../http.js";
+import type {
+  WorkspaceMemberRecord,
+  WorkspaceRole,
+} from "./workspace-members.js";
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+export interface WorkspaceInvite {
+  id: string;
+  workspace_id: string;
+  tenant_id: string;
+  email: string;
+  role: WorkspaceRole;
+  invited_by: string | null;
+  expires_at: string;
+  accepted_at: string | null;
+  inserted_at: string;
+}
+
+export interface WorkspaceInvitePreview {
+  workspace_name: string;
+  tenant_name: string;
+  role: WorkspaceRole;
+  email: string;
+  expires_at: string;
+  expired: boolean;
+  revoked: boolean;
+  accepted: boolean;
+}
+
+// ── Request payloads ─────────────────────────────────────────────────────────
+
+export interface CreateWorkspaceInviteParams {
+  email: string;
+  role?: WorkspaceRole;
+}
+
+// ── Response shapes ───────────────────────────────────────────────────────────
+
+/** Returned when the email was unknown — an invite was created. */
+export interface WorkspaceInviteCreatedResponse {
+  data: WorkspaceInvite;
+  type: "invited";
+}
+
+/** Returned when the email already had a tenant_members row — added directly. */
+export interface WorkspaceMemberAddedResponse {
+  data: WorkspaceMemberRecord;
+  type: "added";
+}
+
+export type CreateWorkspaceInviteResponse =
+  | WorkspaceInviteCreatedResponse
+  | WorkspaceMemberAddedResponse;
+
+export interface WorkspaceInviteListResponse {
+  data: WorkspaceInvite[];
+  total: number;
+}
+
+export interface WorkspaceInviteRevokeResponse {
+  invite_id: string;
+  revoked: boolean;
+}
+
+export interface WorkspaceInvitePreviewResponse {
+  data: WorkspaceInvitePreview;
+}
+
+export interface AcceptWorkspaceInviteResponse {
+  accepted: boolean;
+  workspace_id: string;
+  tenant_id: string;
+  role: WorkspaceRole;
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class WorkspaceInvites {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Create a workspace invite or add a member directly.
+   *
+   * If `email` already maps to a tenant member the user is added directly and
+   * `type === "added"` is returned with a `WorkspaceMemberRecord`. Otherwise
+   * an invite row is created and `type === "invited"` is returned.
+   *
+   * `POST /workspaces/:id/invites`
+   */
+  async create(
+    workspaceId: string,
+    params: CreateWorkspaceInviteParams,
+  ): Promise<CreateWorkspaceInviteResponse> {
+    return this.http.post<CreateWorkspaceInviteResponse>(
+      `/workspaces/${workspaceId}/invites`,
+      params,
+    );
+  }
+
+  /**
+   * List all pending (non-expired, non-accepted, non-revoked) workspace invites.
+   *
+   * `GET /workspaces/:id/invites`
+   */
+  async list(workspaceId: string): Promise<WorkspaceInvite[]> {
+    const res = await this.http.get<WorkspaceInviteListResponse>(
+      `/workspaces/${workspaceId}/invites`,
+    );
+    return res.data ?? [];
+  }
+
+  /**
+   * Revoke a pending workspace invite.
+   *
+   * Already-revoked invites are idempotent (returns `revoked: true`). An invite
+   * that was legitimately accepted throws `409 ALREADY_ACCEPTED`.
+   *
+   * `DELETE /workspaces/:id/invites/:invite_id`
+   */
+  async revoke(
+    workspaceId: string,
+    inviteId: string,
+  ): Promise<WorkspaceInviteRevokeResponse> {
+    return this.http.delete<WorkspaceInviteRevokeResponse>(
+      `/workspaces/${workspaceId}/invites/${inviteId}`,
+    );
+  }
+
+  /**
+   * Preview a workspace invite by token (no auth required).
+   *
+   * Use this to render the invite landing page before prompting the user to
+   * log in or sign up. Returns `null` when the token is unknown or revoked.
+   *
+   * `GET /workspace-invites/:token`
+   */
+  async preview(token: string): Promise<WorkspaceInvitePreview | null> {
+    try {
+      const res = await this.http.get<WorkspaceInvitePreviewResponse>(
+        `/workspace-invites/${token}`,
+      );
+      return res.data ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Accept a workspace invite on behalf of the authenticated user.
+   *
+   * The caller's JWT email must match the invite email (case-insensitive).
+   *
+   * Error codes:
+   * - `INVALID_TOKEN` (404) — token not found.
+   * - `EXPIRED` (410) — invite TTL elapsed.
+   * - `REVOKED` (409) — invite was revoked.
+   * - `ALREADY_ACCEPTED` (409) — already used.
+   * - `EMAIL_MISMATCH` (422) — JWT email differs from invite email.
+   *
+   * `POST /workspace-invites/:token/accept`
+   */
+  async accept(token: string): Promise<AcceptWorkspaceInviteResponse> {
+    return this.http.post<AcceptWorkspaceInviteResponse>(
+      `/workspace-invites/${token}/accept`,
+      {},
+    );
+  }
+}

package/src/resources/workspace-members.test.ts

@@ -0,0 +1,121 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { HttpClient } from "../http.js";
+import { WorkspaceMembers } from "./workspace-members.js";
+
+const mockGet = vi.fn();
+const mockPost = vi.fn();
+const mockPatch = vi.fn();
+const mockDelete = vi.fn();
+const mockRequest = vi.fn();
+
+function makeHttp(): HttpClient {
+  const http = {} as HttpClient;
+  http.get = mockGet;
+  http.post = mockPost;
+  http.patch = mockPatch;
+  http.delete = mockDelete;
+  http.request = mockRequest;
+  return http;
+}
+
+const MEMBER = {
+  user_id: "usr_abc",
+  email: "alice@example.com",
+  name: "Alice",
+  avatar_url: null,
+  role: "member" as const,
+  joined_at: "2026-05-01T10:00:00Z",
+  added_by: null,
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("WorkspaceMembers", () => {
+  describe("list()", () => {
+    it("calls GET /workspaces/:id/members and returns array", async () => {
+      mockGet.mockResolvedValue({ data: [MEMBER] });
+      const resource = new WorkspaceMembers(makeHttp());
+
+      const result = await resource.list("ws-uuid");
+
+      expect(mockGet).toHaveBeenCalledWith("/workspaces/ws-uuid/members");
+      expect(result).toHaveLength(1);
+      expect(result[0].user_id).toBe("usr_abc");
+      expect(result[0].email).toBe("alice@example.com");
+      expect(result[0].role).toBe("member");
+    });
+
+    it("returns empty array when data is empty", async () => {
+      mockGet.mockResolvedValue({ data: [] });
+      const resource = new WorkspaceMembers(makeHttp());
+
+      const result = await resource.list("ws-uuid");
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("add()", () => {
+    it("calls POST /workspaces/:id/members with userId and role", async () => {
+      const record = {
+        user_id: "usr_def",
+        workspace_id: "ws-uuid",
+        role: "member",
+        joined_at: "2026-05-22T09:00:00Z",
+        added_by: "usr_abc",
+      };
+      mockPost.mockResolvedValue({ data: record });
+      const resource = new WorkspaceMembers(makeHttp());
+
+      const result = await resource.add("ws-uuid", {
+        user_id: "usr_def",
+        role: "member",
+      });
+
+      expect(mockPost).toHaveBeenCalledWith(
+        "/workspaces/ws-uuid/members",
+        expect.objectContaining({ user_id: "usr_def", role: "member" }),
+      );
+      expect(result.user_id).toBe("usr_def");
+      expect(result.role).toBe("member");
+    });
+  });
+
+  describe("updateRole()", () => {
+    it("calls PATCH /workspaces/:id/members/:userId with new role", async () => {
+      const updated = {
+        user_id: "usr_def",
+        workspace_id: "ws-uuid",
+        role: "admin",
+        joined_at: "2026-05-22T09:00:00Z",
+        added_by: "usr_abc",
+      };
+      mockPatch.mockResolvedValue({ data: updated });
+      const resource = new WorkspaceMembers(makeHttp());
+
+      const result = await resource.updateRole("ws-uuid", "usr_def", {
+        role: "admin",
+      });
+
+      expect(mockPatch).toHaveBeenCalledWith(
+        "/workspaces/ws-uuid/members/usr_def",
+        { role: "admin" },
+      );
+      expect(result.role).toBe("admin");
+    });
+  });
+
+  describe("remove()", () => {
+    it("calls DELETE /workspaces/:id/members/:userId", async () => {
+      mockDelete.mockResolvedValue({ deleted: true });
+      const resource = new WorkspaceMembers(makeHttp());
+
+      await resource.remove("ws-uuid", "usr_def");
+
+      expect(mockDelete).toHaveBeenCalledWith(
+        "/workspaces/ws-uuid/members/usr_def",
+      );
+    });
+  });
+});

package/src/resources/workspace-members.ts

@@ -0,0 +1,143 @@
+/**
+ * Workspace Members — per-workspace user roster.
+ *
+ * Endpoints:
+ *   GET    /workspaces/:id/members
+ *   POST   /workspaces/:id/members
+ *   PATCH  /workspaces/:id/members/:user_id
+ *   DELETE /workspaces/:id/members/:user_id
+ */
+
+import type { HttpClient } from "../http.js";
+
+// ── Resource shapes ──────────────────────────────────────────────────────────
+
+/** Role a user can hold within a workspace. */
+export type WorkspaceRole = "owner" | "admin" | "member" | "viewer";
+
+/**
+ * Workspace member as returned by `list` — includes denormalised user fields
+ * for display.
+ */
+export interface WorkspaceMember {
+  user_id: string;
+  email: string | null;
+  name: string | null;
+  avatar_url: string | null;
+  role: WorkspaceRole;
+  joined_at: string | null;
+  added_by: string | null;
+}
+
+/** Raw workspace_members row returned after add/update operations. */
+export interface WorkspaceMemberRecord {
+  user_id: string;
+  workspace_id: string;
+  role: WorkspaceRole;
+  joined_at: string | null;
+  added_by: string | null;
+}
+
+// ── Request payloads ─────────────────────────────────────────────────────────
+
+export interface AddWorkspaceMemberParams {
+  /** UUID of the tenant user to add. Must already be an org member. */
+  user_id: string;
+  /** Role to assign; defaults to `"member"`. */
+  role?: WorkspaceRole;
+}
+
+export interface UpdateWorkspaceMemberRoleParams {
+  role: WorkspaceRole;
+}
+
+// ── Response envelopes ───────────────────────────────────────────────────────
+
+export interface WorkspaceMemberListResponse {
+  data: WorkspaceMember[];
+}
+
+export interface WorkspaceMemberRecordResponse {
+  data: WorkspaceMemberRecord;
+}
+
+export interface WorkspaceMemberDeleteResponse {
+  deleted: boolean;
+}
+
+// ── Main resource ─────────────────────────────────────────────────────────────
+
+export class WorkspaceMembers {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * List all members of a workspace.
+   *
+   * `GET /workspaces/:id/members`
+   */
+  async list(workspaceId: string): Promise<WorkspaceMember[]> {
+    const res = await this.http.get<WorkspaceMemberListResponse>(
+      `/workspaces/${workspaceId}/members`,
+    );
+    return res.data ?? (res as unknown as WorkspaceMember[]);
+  }
+
+  /**
+   * Add an existing tenant user to a workspace.
+   *
+   * The `user_id` must already hold a `tenant_members` row for the parent org.
+   * Use {@link WorkspaceInvites.create} to invite someone who is not yet an org
+   * member.
+   *
+   * `POST /workspaces/:id/members`
+   *
+   * @throws `MiosaError` with code `NOT_TENANT_MEMBER` if the user is not an
+   *   org member.
+   */
+  async add(
+    workspaceId: string,
+    params: AddWorkspaceMemberParams,
+  ): Promise<WorkspaceMemberRecord> {
+    const res = await this.http.post<WorkspaceMemberRecordResponse>(
+      `/workspaces/${workspaceId}/members`,
+      params,
+    );
+    return res.data ?? (res as unknown as WorkspaceMemberRecord);
+  }
+
+  /**
+   * Change a workspace member's role.
+   *
+   * `PATCH /workspaces/:id/members/:user_id`
+   */
+  async updateRole(
+    workspaceId: string,
+    userId: string,
+    params: UpdateWorkspaceMemberRoleParams,
+  ): Promise<WorkspaceMemberRecord> {
+    const res = await this.http.patch<WorkspaceMemberRecordResponse>(
+      `/workspaces/${workspaceId}/members/${userId}`,
+      params,
+    );
+    return res.data ?? (res as unknown as WorkspaceMemberRecord);
+  }
+
+  /**
+   * Remove a user from a workspace.
+   *
+   * The last `owner` of a workspace cannot be removed. Promote another member
+   * to `owner` first using {@link updateRole}.
+   *
+   * `DELETE /workspaces/:id/members/:user_id`
+   *
+   * @throws `MiosaError` with code `LAST_OWNER` if the target is the sole owner.
+   */
+  async remove(
+    workspaceId: string,
+    userId: string,
+  ): Promise<WorkspaceMemberDeleteResponse> {
+    return this.http.delete<WorkspaceMemberDeleteResponse>(
+      `/workspaces/${workspaceId}/members/${userId}`,
+    );
+  }
+}