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://ktw-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, removal, and customizable role labels.

// Basic usage with default roles
<MemberList
  organizationId={orgId}
  canManageMembers={isAdmin}
  showInviteButton={true}
  onInviteClick={() => setShowInviteForm(true)}
/>

// With custom roles for your application
<MemberList
  organizationId={orgId}
  canManageMembers={true}
  roles={[
    { value: 'ADMIN', label: 'Administrator' },
    { value: 'MANAGER', label: 'Manager' },
    { value: 'SALES', label: 'Sales Staff' },
    { value: 'SUPPORT', label: 'Support Staff' }
  ]}
  onInviteClick={() => setShowInviteForm(true)}
/>

InviteMemberForm

Form for inviting new members via email with customizable roles.

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

// With custom roles for your application
<InviteMemberForm
  organizationId={orgId}
  roles={[
    { value: 'ADMIN', label: 'Administrator' },
    { value: 'MANAGER', label: 'Manager' },
    { value: 'SALES', label: 'Sales Staff' },
    { value: 'SUPPORT', label: 'Support Staff' }
  ]}
  onSuccess={(invitation) => console.log('Invited:', invitation)}
/>

// Hospital application example
<InviteMemberForm
  organizationId={orgId}
  roles={[
    { value: 'ADMIN', label: 'Administrator' },
    { value: 'DOCTOR', label: 'Doctor' },
    { value: 'NURSE', label: 'Nurse' },
    { value: 'RECEPTIONIST', label: 'Receptionist' }
  ]}
  onSuccess={(invitation) => console.log('Invited:', invitation)}
/>

LogoUploader

Simple logo uploader with drag-and-drop support.

<LogoUploader
  value={logoUrl}
  onChange={setLogoUrl}
  upfilesConfig={{
    baseUrl: 'http://localhost:4012',
    apiKey: 'upk_...',
  }}
  folderPath="logos/"
  size={120}
/>

ImagePicker

Versatile image picker with optional ImageManager integration.

// Basic usage - direct upload
<ImagePicker
  value={imageUrl}
  onChange={(url, image) => setImageUrl(url)}
  upfilesConfig={{
    baseUrl: 'http://localhost:4012',
    apiKey: 'upk_...',
  }}
  label="Cover Image"
  shape="rounded" // 'square' | 'circle' | 'rounded'
  size={150}
/>

// With ImageManager from @thetechfossil/upfiles
import { ImageManager } from '@thetechfossil/upfiles';

<ImagePicker
  value={imageUrl}
  onChange={(url, image) => setImageUrl(url)}
  upfilesConfig={upfilesConfig}
  label="Select Image"
  renderImageManager={({ open, onOpenChange, onSelect, clientOptions }) => (
    <ImageManager
      open={open}
      onOpenChange={onOpenChange}
      onSelect={onSelect}
      clientOptions={clientOptions}
      title="Media Library"
    />
  )}
/>

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 {
  CommonRoles,
  Organization,
  OrganizationMember,
  UserGroup,
  Invitation,
  InvitationStatus
} from '@thetechfossil/organization-sdk';

// Common Roles (convenience constants)
CommonRoles.ADMIN    // 'ADMIN'
CommonRoles.MANAGER  // 'MANAGER'
CommonRoles.SALES    // 'SALES'
CommonRoles.SUPPORT  // 'SUPPORT'
CommonRoles.USER     // 'USER'

// Roles are flexible strings - define your own!
const myCustomRoles = ['ADMIN', 'DOCTOR', 'NURSE', 'PATIENT'];

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

Custom Roles

Roles are now flexible strings - each application can define its own roles without being limited to predefined values.

Quick Example

// Business Application
const businessRoles = [
  { value: 'ADMIN', label: 'Administrator' },
  { value: 'MANAGER', label: 'Manager' },
  { value: 'SALES', label: 'Sales Staff' },
  { value: 'SUPPORT', label: 'Support Staff' },
];

<InviteMemberForm roles={businessRoles} />
<MemberList roles={businessRoles} />

// Hospital Application
const hospitalRoles = [
  { value: 'ADMIN', label: 'Administrator' },
  { value: 'DOCTOR', label: 'Doctor' },
  { value: 'NURSE', label: 'Nurse' },
  { value: 'RECEPTIONIST', label: 'Receptionist' },
];

<InviteMemberForm roles={hospitalRoles} />
<MemberList roles={hospitalRoles} />

// School Application
const schoolRoles = [
  { value: 'ADMIN', label: 'Administrator' },
  { value: 'TEACHER', label: 'Teacher' },
  { value: 'STUDENT', label: 'Student' },
  { value: 'PARENT', label: 'Parent' },
];

<InviteMemberForm roles={schoolRoles} />
<MemberList roles={schoolRoles} />

Common Role Constants

For convenience, the SDK provides common role constants:

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

CommonRoles.ADMIN    // 'ADMIN'
CommonRoles.MANAGER  // 'MANAGER'
CommonRoles.SALES    // 'SALES'
CommonRoles.SUPPORT  // 'SUPPORT'
CommonRoles.USER     // 'USER'

Theming

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

License

MIT