Organization Management

/**
 * Find organizations with optional search and pagination
 * @param query - Optional search and pagination parameters
 * @returns Array of organization representations
 */
find(query?: OrganizationsQuery): Promise<OrganizationRepresentation[]>;

/**
 * Create a new organization
 * @param organization - Organization configuration
 * @returns Created organization representation
 */
create(organization: OrganizationRepresentation): Promise<OrganizationRepresentation>;

/**
 * Find a specific organization by ID
 * @param params - Organization identifier
 * @returns Organization representation or undefined if not found
 */
findOne(params: { orgId: string }): Promise<OrganizationRepresentation | undefined>;

/**
 * Update an existing organization
 * @param params - Organization identifier
 * @param organization - Updated organization configuration
 */
update(params: { orgId: string }, organization: OrganizationRepresentation): Promise<void>;

/**
 * Delete an organization
 * @param params - Organization identifier
 */
del(params: { orgId: string }): Promise<void>;

// List all organizations
const orgs = await kcAdminClient.organizations.find();
console.log("Organizations:", orgs.map(o => o.name));

// Search organizations with pagination
const searchResults = await kcAdminClient.organizations.find({
  search: "acme",
  first: 0,
  max: 10,
});

// Create new organization
const newOrg = await kcAdminClient.organizations.create({
  name: "Acme Corporation",
  displayName: "Acme Corp",
  description: "Leading provider of innovative solutions",
  enabled: true,
  attributes: {
    industry: ["technology"],
    region: ["north-america"],
    size: ["enterprise"],
  },
});

console.log("Created organization:", newOrg.id);

// Get specific organization
const org = await kcAdminClient.organizations.findOne({
  orgId: newOrg.id!,
});

// Update organization
await kcAdminClient.organizations.update(
  { orgId: newOrg.id! },
  {
    displayName: "Acme Corporation Ltd",
    description: "Updated: Leading provider of innovative solutions",
    attributes: {
      industry: ["technology", "consulting"],
      region: ["north-america", "europe"],
      size: ["enterprise"],
    },
  }
);

// Delete organization
await kcAdminClient.organizations.del({ orgId: "org-to-delete" });

/**
 * Find members of an organization
 * @param params - Organization identifier
 * @param query - Optional search and pagination parameters
 * @returns Array of organization members
 */
findMembers(params: { orgId: string }, query?: MembersQuery): Promise<UserRepresentation[]>;

/**
 * Invite user to organization
 * @param params - Organization identifier
 * @param invitation - Invitation details
 */
inviteUser(params: { orgId: string }, invitation: InvitationRequest): Promise<void>;

/**
 * Add existing user to organization
 * @param params - Organization and user identifiers
 */
addMember(params: { orgId: string; userId: string }): Promise<void>;

/**
 * Remove user from organization
 * @param params - Organization and user identifiers
 */
removeMember(params: { orgId: string; userId: string }): Promise<void>;

// Get all organization members
const members = await kcAdminClient.organizations.findMembers({
  orgId: organizationId,
});

console.log("Organization members:", members.map(u => u.username));

// Search members with pagination
const memberPage = await kcAdminClient.organizations.findMembers(
  { orgId: organizationId },
  {
    search: "john",
    first: 0,
    max: 20,
  }
);

// Invite user by email
await kcAdminClient.organizations.inviteUser(
  { orgId: organizationId },
  {
    email: "newuser@example.com",
    firstName: "John",
    lastName: "Doe",
    roles: ["member"],
    redirectUri: "https://myapp.com/welcome",
  }
);

// Add existing user to organization
const existingUser = await kcAdminClient.users.find({
  username: "existing-user",
}).then(users => users[0]);

await kcAdminClient.organizations.addMember({
  orgId: organizationId,
  userId: existingUser.id!,
});

// Remove member from organization
await kcAdminClient.organizations.removeMember({
  orgId: organizationId,
  userId: existingUser.id!,
});

/**
 * List identity providers for an organization
 * @param params - Organization identifier
 * @returns Array of organization identity providers
 */
listIdentityProviders(params: { orgId: string }): Promise<OrganizationIdentityProviderRepresentation[]>;

/**
 * Add identity provider to organization
 * @param params - Organization identifier
 * @param provider - Identity provider configuration
 */
addIdentityProvider(params: {
  orgId: string;
}, provider: OrganizationIdentityProviderRepresentation): Promise<void>;

/**
 * Update organization identity provider
 * @param params - Organization and provider identifiers
 * @param provider - Updated provider configuration
 */
updateIdentityProvider(params: {
  orgId: string;
  alias: string;
}, provider: OrganizationIdentityProviderRepresentation): Promise<void>;

/**
 * Remove identity provider from organization
 * @param params - Organization and provider identifiers
 */
removeIdentityProvider(params: {
  orgId: string;
  alias: string;
}): Promise<void>;

// List organization identity providers
const orgIdPs = await kcAdminClient.organizations.listIdentityProviders({
  orgId: organizationId,
});

console.log("Organization IdPs:", orgIdPs.map(idp => idp.alias));

// Add SAML identity provider to organization
await kcAdminClient.organizations.addIdentityProvider(
  { orgId: organizationId },
  {
    alias: "org-saml",
    providerId: "saml",
    enabled: true,
    config: {
      singleSignOnServiceUrl: "https://org.example.com/saml/sso",
      singleLogoutServiceUrl: "https://org.example.com/saml/slo",
      nameIDPolicyFormat: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    },
  }
);

// Update identity provider
await kcAdminClient.organizations.updateIdentityProvider(
  { orgId: organizationId, alias: "org-saml" },
  {
    enabled: false, // Temporarily disable
    config: {
      singleSignOnServiceUrl: "https://new-org.example.com/saml/sso",
    },
  }
);

// Remove identity provider
await kcAdminClient.organizations.removeIdentityProvider({
  orgId: organizationId,
  alias: "org-saml",
});

/**
 * Organization search and pagination query parameters
 */
interface OrganizationsQuery {
  /** Search term for organization name */
  search?: string;
  /** Exact match for search term */
  exact?: boolean;
  /** Number of results to skip */
  first?: number;
  /** Maximum number of results to return */
  max?: number;
}

/**
 * Organization members query parameters
 */
interface MembersQuery {
  /** Search term for member username/email */
  search?: string;
  /** Exact match for search term */
  exact?: boolean;
  /** Number of results to skip */
  first?: number;
  /** Maximum number of results to return */
  max?: number;
}

/**
 * User invitation request
 */
interface InvitationRequest {
  /** User email address */
  email: string;
  /** User first name */
  firstName?: string;
  /** User last name */
  lastName?: string;
  /** Organization roles to assign */
  roles?: string[];
  /** Redirect URI after acceptance */
  redirectUri?: string;
  /** Invitation expiration time in seconds */
  expirationTime?: number;
  /** Custom invitation message */
  message?: string;
}

/**
 * Organization representation
 */
interface OrganizationRepresentation {
  /** Organization unique identifier */
  id?: string;
  /** Organization name (must be unique) */
  name?: string;
  /** Display name */
  displayName?: string;
  /** Organization description */
  description?: string;
  /** Whether organization is enabled */
  enabled?: boolean;
  /** Custom organization attributes */
  attributes?: Record<string, string[]>;
  /** Organization domains */
  domains?: OrganizationDomainRepresentation[];
  /** Organization members */
  members?: UserRepresentation[];
  /** Identity providers */
  identityProviders?: OrganizationIdentityProviderRepresentation[];
}

/**
 * Organization domain configuration
 */
interface OrganizationDomainRepresentation {
  /** Domain name */
  name?: string;
  /** Whether domain is verified */
  verified?: boolean;
}

/**
 * Organization-specific identity provider
 */
interface OrganizationIdentityProviderRepresentation {
  /** Identity provider alias */
  alias?: string;
  /** Provider type (saml, oidc, etc.) */
  providerId?: string;
  /** Whether provider is enabled */
  enabled?: boolean;
  /** Provider configuration */
  config?: Record<string, string>;
}

// Pattern 1: Multi-tenant organization setup
const organizations = [
  { name: "acme-corp", displayName: "Acme Corporation" },
  { name: "beta-inc", displayName: "Beta Inc" },
  { name: "gamma-ltd", displayName: "Gamma Ltd" },
];

for (const orgData of organizations) {
  const org = await kcAdminClient.organizations.create({
    ...orgData,
    enabled: true,
    attributes: {
      tier: ["premium"],
      region: ["us-east"],
    },
  });
  
  // Set up organization-specific identity provider
  await kcAdminClient.organizations.addIdentityProvider(
    { orgId: org.id! },
    {
      alias: `${orgData.name}-saml`,
      providerId: "saml",
      enabled: true,
      config: {
        singleSignOnServiceUrl: `https://${orgData.name}.example.com/saml/sso`,
      },
    }
  );
}

// Pattern 2: Bulk user invitation
const invitations = [
  { email: "admin@acme.com", roles: ["admin", "member"] },
  { email: "user1@acme.com", roles: ["member"] },
  { email: "user2@acme.com", roles: ["member"] },
];

for (const invitation of invitations) {
  await kcAdminClient.organizations.inviteUser(
    { orgId: organizationId },
    {
      ...invitation,
      redirectUri: "https://myapp.com/org-welcome",
      expirationTime: 86400 * 7, // 7 days
    }
  );
}

// Pattern 3: Organization member management
const orgMembers = await kcAdminClient.organizations.findMembers({
  orgId: organizationId,
});

// Find inactive members and send reminder
const inactiveMembers = orgMembers.filter(member => {
  // Logic to determine inactive members
  return member.attributes?.lastLogin?.[0] < thirtyDaysAgo;
});

for (const member of inactiveMembers) {
  // Send reactivation email or remove from organization
  console.log(`Member ${member.username} has been inactive`);
}