feat(docs): add package READMEs and publish metadata; update web package publish order
This commit is contained in:
@@ -0,0 +1,312 @@
|
||||
# @idp.global/interfaces
|
||||
|
||||
TypeScript interfaces and type definitions for the idp.global Identity Provider platform.
|
||||
|
||||
## Overview
|
||||
|
||||
This package provides the complete type system for idp.global, including data models, API request/response interfaces, and OIDC definitions. Use this package when building applications that integrate with idp.global or when you need type-safe interactions with the IdP API.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @idp.global/interfaces
|
||||
# or
|
||||
pnpm add @idp.global/interfaces
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```typescript
|
||||
import { data, request, tags } from '@idp.global/interfaces';
|
||||
|
||||
// Data interfaces
|
||||
const user: data.IUser = {
|
||||
id: 'user_123',
|
||||
data: {
|
||||
name: 'John Doe',
|
||||
username: 'johndoe',
|
||||
email: 'john@example.com',
|
||||
status: 'active',
|
||||
connectedOrgs: ['org_1', 'org_2'],
|
||||
},
|
||||
};
|
||||
|
||||
// Organization interface
|
||||
const org: data.IOrganization = {
|
||||
id: 'org_1',
|
||||
data: {
|
||||
name: 'Acme Corp',
|
||||
slug: 'acme',
|
||||
billingPlanId: 'plan_free',
|
||||
roleIds: ['role_admin', 'role_member'],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
ts_interfaces/
|
||||
├── data/ # Data model interfaces
|
||||
│ ├── loint-reception.user.ts # User profiles
|
||||
│ ├── loint-reception.organization.ts # Organizations
|
||||
│ ├── loint-reception.role.ts # RBAC roles
|
||||
│ ├── loint-reception.app.ts # OAuth applications
|
||||
│ ├── loint-reception.oidc.ts # OIDC tokens & flows
|
||||
│ ├── loint-reception.jwt.ts # JWT structures
|
||||
│ ├── loint-reception.loginsession.ts # Login sessions
|
||||
│ ├── loint-reception.billingplan.ts # Billing plans
|
||||
│ ├── loint-reception.device.ts # Device management
|
||||
│ ├── loint-reception.activity.ts # Activity logs
|
||||
│ ├── loint-reception.userinvitation.ts # Invitations
|
||||
│ └── loint-reception.appconnection.ts # App connections
|
||||
├── request/ # API request/response interfaces
|
||||
│ ├── loint-reception.login.ts # Authentication
|
||||
│ ├── loint-reception.registration.ts # User registration
|
||||
│ ├── loint-reception.user.ts # User management
|
||||
│ ├── loint-reception.organization.ts # Org management
|
||||
│ ├── loint-reception.jwt.ts # JWT operations
|
||||
│ ├── loint-reception.apitoken.ts # API tokens
|
||||
│ ├── loint-reception.app.ts # App management
|
||||
│ ├── loint-reception.billingplan.ts # Billing
|
||||
│ └── loint-reception.admin.ts # Admin operations
|
||||
└── tags/ # Tag definitions
|
||||
```
|
||||
|
||||
## Data Interfaces
|
||||
|
||||
### User (`IUser`)
|
||||
|
||||
```typescript
|
||||
interface IUser {
|
||||
id: string;
|
||||
data: {
|
||||
name: string;
|
||||
username: string;
|
||||
email: string;
|
||||
mobileNumber?: string;
|
||||
password?: string; // Only during initial setting
|
||||
passwordHash?: string; // For validation
|
||||
status: 'new' | 'active' | 'deleted' | 'suspended';
|
||||
connectedOrgs: string[]; // Organization IDs
|
||||
isGlobalAdmin?: boolean; // Platform admin flag
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Organization (`IOrganization`)
|
||||
|
||||
```typescript
|
||||
interface IOrganization {
|
||||
id: string;
|
||||
data: {
|
||||
name: string;
|
||||
slug: string;
|
||||
billingPlanId: string;
|
||||
roleIds: string[];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Role (`IRole`)
|
||||
|
||||
```typescript
|
||||
interface IRole {
|
||||
id: string;
|
||||
data: {
|
||||
name: string;
|
||||
organizationId: string;
|
||||
userId: string;
|
||||
permissions: string[];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### OAuth Application Types
|
||||
|
||||
```typescript
|
||||
// Global platform apps (maintained by platform admins)
|
||||
interface IGlobalApp {
|
||||
id: string;
|
||||
type: 'globalApp';
|
||||
data: {
|
||||
name: string;
|
||||
description: string;
|
||||
iconBase64?: string;
|
||||
oauthCredentials?: IOAuthCredentials;
|
||||
};
|
||||
}
|
||||
|
||||
// Partner apps (third-party integrations)
|
||||
interface IPartnerApp {
|
||||
id: string;
|
||||
type: 'partnerApp';
|
||||
data: {
|
||||
name: string;
|
||||
description: string;
|
||||
ownerOrganizationId: string;
|
||||
oauthCredentials?: IOAuthCredentials;
|
||||
};
|
||||
}
|
||||
|
||||
// Custom OIDC clients
|
||||
interface ICustomOidcApp {
|
||||
id: string;
|
||||
type: 'customOidcApp';
|
||||
data: {
|
||||
name: string;
|
||||
description: string;
|
||||
ownerOrganizationId: string;
|
||||
oauthCredentials: IOAuthCredentials;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### OAuth Credentials
|
||||
|
||||
```typescript
|
||||
interface IOAuthCredentials {
|
||||
clientId: string;
|
||||
clientSecretHash: string;
|
||||
redirectUris: string[];
|
||||
scopes: string[];
|
||||
grantTypes: ('authorization_code' | 'refresh_token' | 'client_credentials')[];
|
||||
}
|
||||
```
|
||||
|
||||
## OIDC Interfaces
|
||||
|
||||
### Authorization Code
|
||||
|
||||
```typescript
|
||||
interface IAuthorizationCode {
|
||||
code: string;
|
||||
clientId: string;
|
||||
userId: string;
|
||||
scopes: string[];
|
||||
redirectUri: string;
|
||||
codeChallenge?: string;
|
||||
codeChallengeMethod?: 'S256';
|
||||
expiresAt: number;
|
||||
used: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
### Token Response
|
||||
|
||||
```typescript
|
||||
interface ITokenResponse {
|
||||
access_token: string;
|
||||
token_type: 'Bearer';
|
||||
expires_in: number;
|
||||
refresh_token?: string;
|
||||
id_token?: string;
|
||||
scope: string;
|
||||
}
|
||||
```
|
||||
|
||||
### UserInfo Response
|
||||
|
||||
```typescript
|
||||
interface IUserInfoResponse {
|
||||
sub: string;
|
||||
name?: string;
|
||||
preferred_username?: string;
|
||||
email?: string;
|
||||
email_verified?: boolean;
|
||||
organizations?: Array<{
|
||||
id: string;
|
||||
name: string;
|
||||
slug: string;
|
||||
roles: string[];
|
||||
}>;
|
||||
roles?: string[];
|
||||
}
|
||||
```
|
||||
|
||||
### ID Token Claims
|
||||
|
||||
```typescript
|
||||
interface IIdTokenClaims {
|
||||
iss: string; // Issuer
|
||||
sub: string; // Subject (user ID)
|
||||
aud: string; // Audience (client ID)
|
||||
exp: number; // Expiration time
|
||||
iat: number; // Issued at
|
||||
nonce?: string; // Replay protection
|
||||
name?: string;
|
||||
email?: string;
|
||||
email_verified?: boolean;
|
||||
organizations?: Array<{...}>;
|
||||
roles?: string[];
|
||||
}
|
||||
```
|
||||
|
||||
## Request Interfaces
|
||||
|
||||
All API requests follow the TypedRequest pattern:
|
||||
|
||||
```typescript
|
||||
interface IReq_LoginWithEmailOrUsernameAndPassword {
|
||||
method: 'loginWithEmailOrUsernameAndPassword';
|
||||
request: {
|
||||
username: string;
|
||||
password: string;
|
||||
};
|
||||
response: {
|
||||
refreshToken?: string;
|
||||
twoFaNeeded: boolean;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Authentication Requests
|
||||
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_LoginWithEmailOrUsernameAndPassword` | `loginWithEmailOrUsernameAndPassword` | Password login |
|
||||
| `IReq_LoginWithEmail` | `loginWithEmail` | Magic link request |
|
||||
| `IReq_LoginWithEmailAfterEmailTokenAquired` | `loginWithEmailAfterEmailTokenAquired` | Magic link verification |
|
||||
| `IReq_LoginWithApiToken` | `loginWithApiToken` | API token login |
|
||||
| `IReq_RefreshJwt` | `refreshJwt` | Refresh access token |
|
||||
| `ILogoutRequest` | `logout` | End session |
|
||||
|
||||
### User Management Requests
|
||||
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetUserData` | `getUserData` | Get current user |
|
||||
| `IReq_SetUserData` | `setUserData` | Update user profile |
|
||||
| `IReq_GetUserSessions` | `getUserSessions` | List active sessions |
|
||||
| `IReq_ResetPassword` | `resetPassword` | Request password reset |
|
||||
| `IReq_SetNewPassword` | `setNewPassword` | Set new password |
|
||||
|
||||
### Organization Requests
|
||||
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_CreateOrganization` | `createOrganization` | Create new org |
|
||||
| `IReq_GetOrgMembers` | `getOrgMembers` | List org members |
|
||||
| `IReq_CreateInvitation` | `createInvitation` | Invite user |
|
||||
| `IReq_AcceptInvitation` | `acceptInvitation` | Accept invite |
|
||||
|
||||
### JWT Operations
|
||||
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetPublicKeyForValidation` | `getPublicKeyForValidation` | Get JWT public key |
|
||||
| `IReq_GetJwtIdBlocklist` | `getJwtIdBlocklist` | Get revoked token IDs |
|
||||
|
||||
## Supported OIDC Scopes
|
||||
|
||||
| Scope | Description |
|
||||
|-------|-------------|
|
||||
| `openid` | Required for OIDC flows |
|
||||
| `profile` | User's name and username |
|
||||
| `email` | User's email address |
|
||||
| `organizations` | User's organization memberships |
|
||||
| `roles` | User's roles within organizations |
|
||||
|
||||
## License
|
||||
|
||||
MIT - See the main repository for full license details.
|
||||
Reference in New Issue
Block a user