Organization SDK

SDK for accessing the organization service from Next.js or React applications. Includes pre-built UI components and hooks for managing organizations, members, and invitations.

📚 Documentation

Full documentation available at: https://ttf-organization-docs.netlify.app/

For complete guides, API reference, examples, and integration instructions, visit the documentation site.

Installation

npm install @thetechfossil/organization-sdk

Quick Start

1. Setup Provider

Wrap your app with the OrganizationProvider:

import { OrganizationProvider } from '@thetechfossil/organization-sdk';

function App() {
  return (
    <OrganizationProvider
      config={{
        baseUrl: 'http://localhost:4009',
        getToken: () => localStorage.getItem('token') || '',
      }}
    >
      <YourApp />
    </OrganizationProvider>
  );
}

2. Use Pre-built Components

import {
  OrganizationList,
  CreateOrganizationForm,
  OrganizationDropdown,
  MemberList,
  InviteMemberForm
} from '@thetechfossil/organization-sdk';

function MyPage() {
  const [selectedOrg, setSelectedOrg] = useState(null);

  return (
    <div>
      {/* List all organizations */}
      <OrganizationList
        onSelect={(org) => setSelectedOrg(org)}
        onCreateClick={() => setShowCreateForm(true)}
      />

      {/* Organization dropdown selector */}
      <OrganizationDropdown
        value={selectedOrg?.id}
        onChange={(id, org) => setSelectedOrg(org)}
      />

      {/* Create organization form */}
      <CreateOrganizationForm
        onSuccess={(org) => console.log('Created:', org)}
        onCancel={() => setShowCreateForm(false)}
      />

      {/* Member list with management */}
      <MemberList
        organizationId={selectedOrg?.id}
        canManageMembers={true}
        onInviteClick={() => setShowInviteForm(true)}
      />

      {/* Invite member form */}
      <InviteMemberForm
        organizationId={selectedOrg?.id}
        onSuccess={(invitation) => console.log('Invited:', invitation)}
      />
    </div>
  );
}

UI Components

CreateOrganizationForm

Form for creating a new organization with auto-generated slug.

<CreateOrganizationForm
  onSuccess={(organization) => {
    console.log('Created:', organization);
  }}
  onCancel={() => setShowForm(false)}
/>

OrganizationList

Grid display of all user's organizations with optional create button.

<OrganizationList
  onSelect={(org) => navigate(`/org/${org.id}`)}
  onCreateClick={() => setShowCreateForm(true)}
  showCreateButton={true}
/>

OrganizationDropdown

Dropdown selector for choosing an organization.

<OrganizationDropdown
  value={currentOrgId}
  onChange={(id, org) => setCurrentOrg(org)}
  placeholder="Select organization"
/>

MemberList

List of organization members with role management and removal.

<MemberList
  organizationId={orgId}
  canManageMembers={isAdmin}
  showInviteButton={true}
  onInviteClick={() => setShowInviteForm(true)}
/>

InviteMemberForm

Form for inviting new members via email.

<InviteMemberForm
  organizationId={orgId}
  onSuccess={(invitation) => {
    console.log('Invitation sent:', invitation);
  }}
  onCancel={() => setShowForm(false)}
/>

Hooks

useOrganizationClient

Get the organization client instance.

const client = useOrganizationClient();

useOrganizations

Manage organizations list.

const { organizations, loading, error, refetch, createOrganization } = useOrganizations(client);

useOrganization

Get single organization details.

const { organization, loading, error, updateOrganization } = useOrganization(client, orgId);

useMembers

Manage organization members.

const { members, loading, error, addMember, removeMember } = useMembers(client, orgId);

useInvitations

Manage invitations.

const { invitations, loading, error, inviteMember } = useInvitations(client, orgId);

Server-Side Usage

For Next.js API routes or server components:

import { OrganizationClient } from '@thetechfossil/organization-sdk';

const client = new OrganizationClient({
  baseUrl: process.env.ORGANIZATION_SERVICE_URL!,
  getToken: async () => {
    const session = await getServerSession();
    return session.token;
  },
});

const organizations = await client.getMyOrganizations();

API Reference

Client Methods

Organizations:

• createOrganization(data: CreateOrganizationDto): Promise<Organization>
• getOrganization(id: string): Promise<Organization>
• getMyOrganizations(): Promise<Organization[]>
• updateOrganization(id: string, data: UpdateOrganizationDto): Promise<Organization>
• deleteOrganization(id: string): Promise<void>

Members:

• addMember(organizationId: string, data: AddMemberDto): Promise<OrganizationMember>
• getMembers(organizationId: string): Promise<OrganizationMember[]>
• updateMember(memberId: string, data: UpdateMemberDto): Promise<OrganizationMember>
• removeMember(memberId: string): Promise<void>

Groups:

• createGroup(organizationId: string, data: CreateGroupDto): Promise<UserGroup>
• getGroups(organizationId: string): Promise<UserGroup[]>
• addMemberToGroup(groupId: string, memberId: string): Promise<void>
• removeMemberFromGroup(groupId: string, memberId: string): Promise<void>
• deleteGroup(groupId: string): Promise<void>

Invitations:

• inviteMember(organizationId: string, data: InviteMemberDto): Promise<Invitation>
• acceptInvitation(token: string): Promise<Organization>
• getInvitations(organizationId: string): Promise<Invitation[]>

Types

import {
  MemberRole,
  Organization,
  OrganizationMember,
  UserGroup,
  Invitation,
  InvitationStatus
} from '@thetechfossil/organization-sdk';

// Member Roles
MemberRole.ADMIN
MemberRole.USER
MemberRole.STAFF
MemberRole.DOCTOR
MemberRole.PATIENT

// Invitation Status
InvitationStatus.PENDING
InvitationStatus.ACCEPTED
InvitationStatus.REJECTED
InvitationStatus.EXPIRED

Theming

Components automatically adapt to light/dark mode based on system preferences or the dark class on the document element.

License

MIT