@feelflow/ffid-sdk 0.1.0

package/dist/legal/index.d.cts

@@ -0,0 +1,332 @@
+/**
+ * FFID SDK Shared Constants
+ *
+ * Constants shared across all SDK entry points (main client + legal client).
+ * Centralizing these prevents drift during domain/URL changes.
+ */
+/** Default FFID API base URL (production) */
+declare const DEFAULT_API_BASE_URL = "https://id.feelflow.co.jp";
+
+/**
+ * FFID Legal SDK Type Definitions
+ *
+ * Types for the FeelFlow ID Legal Document SDK.
+ * Used by external services to manage legal document agreements
+ * via Service API key authentication.
+ */
+/**
+ * Configuration for the FFID Legal Client
+ *
+ * Unlike FFIDConfig (which uses Cookie auth), this uses
+ * X-Service-Api-Key header for server-to-server communication.
+ */
+interface FFIDLegalClientConfig {
+    /** Service API key (format: ffid_sk_live_xxx or ffid_sk_test_xxx) */
+    apiKey: string;
+    /** FFID API base URL (defaults to https://id.feelflow.co.jp) */
+    apiBaseUrl?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom logger */
+    logger?: FFIDLegalLogger;
+}
+/**
+ * Logger interface for Legal SDK
+ */
+interface FFIDLegalLogger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/**
+ * Legal document types
+ */
+type FFIDLegalDocumentType = 'terms_of_service' | 'privacy_policy' | 'cookie_policy' | 'acceptable_use_policy' | 'data_processing_agreement' | 'service_level_agreement' | 'other';
+/**
+ * Agreement methods
+ */
+type FFIDAgreementMethod = 'explicit_checkbox' | 'click_through' | 'continued_use' | 'electronic_signature';
+/**
+ * Legal document returned from the API
+ */
+interface FFIDLegalDocument {
+    /** Document ID (UUID) */
+    id: string;
+    /** Document type */
+    type: FFIDLegalDocumentType;
+    /** Document title */
+    title: string;
+    /** Document version (e.g., "1.0.0") */
+    version: string;
+    /** Document content (Markdown) */
+    content: string;
+    /** Summary of the document */
+    summary: string | null;
+    /** Effective date (ISO 8601) */
+    effectiveDate: string;
+    /** Whether this document is currently active */
+    isActive: boolean;
+    /** Service scope: 'platform' or specific service ID */
+    serviceScope: string;
+    /** Whether agreement is required to use the service */
+    requiresAgreement: boolean;
+    /** SHA-256 hash of the content */
+    contentHash: string;
+    /** Created timestamp (ISO 8601) */
+    createdAt: string;
+    /** Updated timestamp (ISO 8601) */
+    updatedAt: string;
+}
+/**
+ * Service user agreement record
+ */
+interface FFIDServiceUserAgreement {
+    /** Agreement ID (UUID) */
+    id: string;
+    /** Service ID (UUID) */
+    serviceId: string;
+    /** External user ID (from the calling service) */
+    externalUserId: string;
+    /** External user email (optional) */
+    externalUserEmail: string | null;
+    /** Document ID (UUID) */
+    documentId: string;
+    /** Agreement timestamp (ISO 8601) */
+    agreedAt: string;
+    /** Method of agreement */
+    agreementMethod: FFIDAgreementMethod;
+    /** IP address at time of agreement */
+    ipAddress: string | null;
+    /** User agent at time of agreement */
+    userAgent: string | null;
+    /** Document version at time of agreement */
+    documentVersion: string;
+    /** Document title at time of agreement */
+    documentTitle: string;
+    /** Document content hash at time of agreement */
+    documentHash: string;
+    /** Additional metadata */
+    metadata: Record<string, unknown>;
+    /** Created timestamp (ISO 8601) */
+    createdAt: string;
+}
+/**
+ * Request to record an agreement
+ */
+interface FFIDRecordAgreementRequest {
+    /** External user ID (from the calling service, e.g., Google OAuth ID) */
+    externalUserId: string;
+    /** External user email (optional) */
+    externalUserEmail?: string;
+    /** Document ID to agree to */
+    documentId: string;
+    /** Method of agreement (defaults to 'click_through') */
+    agreementMethod?: FFIDAgreementMethod;
+    /** IP address of the user (if not provided, extracted from request) */
+    ipAddress?: string;
+    /** User agent of the user (if not provided, extracted from request) */
+    userAgent?: string;
+    /** Additional metadata to store with the agreement */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Response from recording an agreement
+ */
+interface FFIDRecordAgreementResponse {
+    /** Success message */
+    message: string;
+    /** Created agreement ID */
+    agreementId: string;
+    /** Document ID that was agreed to */
+    documentId: string;
+    /** External user ID */
+    externalUserId: string;
+}
+/**
+ * Agreement check result (discriminated union for type safety)
+ *
+ * When hasAgreed is true, agreement is guaranteed to be present.
+ * When hasAgreed is false, agreement is null.
+ */
+type FFIDAgreementCheckResult = {
+    hasAgreed: true;
+    agreement: FFIDServiceUserAgreement;
+} | {
+    hasAgreed: false;
+    agreement: null;
+};
+/**
+ * Pending agreement info
+ */
+interface FFIDPendingAgreement {
+    /** Document ID (UUID) */
+    documentId: string;
+    /** Document type */
+    documentType: FFIDLegalDocumentType;
+    /** Document title */
+    documentTitle: string;
+    /** Document version */
+    documentVersion: string;
+    /** Effective date (ISO 8601) */
+    effectiveDate: string;
+}
+/**
+ * Response from get pending agreements
+ */
+interface FFIDPendingAgreementsResponse {
+    /** List of pending documents */
+    pendingDocuments: FFIDPendingAgreement[];
+    /** Number of pending documents */
+    count: number;
+    /** Whether there are any pending documents */
+    hasPending: boolean;
+}
+/**
+ * Known SDK error codes (generated client-side)
+ */
+type FFIDLegalSdkErrorCode = 'MISSING_API_KEY' | 'NETWORK_ERROR' | 'PARSE_ERROR' | 'UNKNOWN_ERROR';
+/**
+ * Known server error codes (returned from FFID API)
+ */
+type FFIDLegalServerErrorCode = 'INVALID_API_KEY' | 'INSUFFICIENT_SCOPE' | 'DOCUMENT_NOT_FOUND' | 'ALREADY_AGREED' | 'VALIDATION_ERROR' | 'INTERNAL_ERROR' | 'NOT_FOUND' | 'UNAUTHORIZED' | 'FORBIDDEN';
+/**
+ * All known error codes (SDK + Server)
+ * Uses intersection with string to allow future unknown codes
+ */
+type FFIDLegalErrorCode = FFIDLegalSdkErrorCode | FFIDLegalServerErrorCode | (string & Record<never, never>);
+/**
+ * Server error details structure
+ */
+interface FFIDLegalServerError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Server response envelope from FFID Legal API (discriminated union)
+ *
+ * All API responses follow this structure with success flag as discriminator.
+ * - When success is true, data is guaranteed to be present
+ * - When success is false, error is guaranteed to be present
+ *
+ * The SDK transforms this into FFIDLegalApiResponse<T>.
+ */
+type FFIDLegalServerResponse<T> = {
+    success: true;
+    data: T;
+    error?: undefined;
+} | {
+    success: false;
+    data?: undefined;
+    error: FFIDLegalServerError;
+};
+/**
+ * Error from the Legal SDK
+ */
+interface FFIDLegalError {
+    /** Error code */
+    code: FFIDLegalErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+}
+/**
+ * API response wrapper (discriminated union for type safety)
+ *
+ * Either data is present (success) or error is present (failure), never both.
+ * This pattern ensures callers handle both cases explicitly.
+ */
+type FFIDLegalApiResponse<T> = {
+    data: T;
+    error?: undefined;
+} | {
+    data?: undefined;
+    error: FFIDLegalError;
+};
+
+/**
+ * FFID Legal API Client
+ *
+ * Handles API communication for legal document operations.
+ * Uses Service API key authentication (X-Service-Api-Key header)
+ * for server-to-server communication.
+ *
+ * @example
+ * ```typescript
+ * import { createFFIDLegalClient } from '@feelflow/ffid-sdk/legal'
+ *
+ * const legal = createFFIDLegalClient({
+ *   apiKey: process.env.FFID_SERVICE_API_KEY!,
+ * })
+ *
+ * // Get all documents
+ * const { data, error } = await legal.getDocuments()
+ *
+ * // Record agreement
+ * await legal.recordAgreement({
+ *   externalUserId: user.google_id,
+ *   documentId: doc.id,
+ * })
+ *
+ * // Check agreement
+ * const check = await legal.checkAgreement(userId, docId)
+ * ```
+ */
+
+/**
+ * Error codes used by the Legal SDK
+ */
+declare const FFID_LEGAL_ERROR_CODES: {
+    /** API key is missing */
+    readonly MISSING_API_KEY: "MISSING_API_KEY";
+    /** Network request failed (fetch threw) */
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    /** Server returned non-JSON response */
+    readonly PARSE_ERROR: "PARSE_ERROR";
+    /** Server returned error without structured error body */
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+    /** Input validation failed (empty required parameters) */
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+};
+/**
+ * Creates an FFID Legal API client instance
+ *
+ * @param config - Client configuration
+ * @returns Legal client instance
+ *
+ * @example
+ * ```typescript
+ * const legal = createFFIDLegalClient({
+ *   apiKey: process.env.FFID_SERVICE_API_KEY!,
+ *   apiBaseUrl: 'https://id.feelflow.co.jp',
+ *   debug: true,
+ * })
+ * ```
+ */
+declare function createFFIDLegalClient(config: FFIDLegalClientConfig): {
+    /** Get all legal documents available to this service */
+    getDocuments: () => Promise<FFIDLegalApiResponse<{
+        documents: FFIDLegalDocument[];
+        count: number;
+    }>>;
+    /** Get a specific legal document by ID */
+    getDocument: (documentId: string) => Promise<FFIDLegalApiResponse<{
+        document: FFIDLegalDocument;
+    }>>;
+    /** Record a user's agreement to a legal document */
+    recordAgreement: (request: FFIDRecordAgreementRequest) => Promise<FFIDLegalApiResponse<FFIDRecordAgreementResponse>>;
+    /** Check if a user has agreed to a specific document */
+    checkAgreement: (externalUserId: string, documentId: string) => Promise<FFIDLegalApiResponse<FFIDAgreementCheckResult>>;
+    /** Get all documents that a user has not yet agreed to */
+    getPendingAgreements: (externalUserId: string) => Promise<FFIDLegalApiResponse<FFIDPendingAgreementsResponse>>;
+    /** Resolved logger instance */
+    logger: FFIDLegalLogger;
+    /** API base URL */
+    baseUrl: string;
+};
+/** Type of the FFID Legal client */
+type FFIDLegalClient = ReturnType<typeof createFFIDLegalClient>;
+
+export { DEFAULT_API_BASE_URL, type FFIDAgreementCheckResult, type FFIDAgreementMethod, type FFIDLegalApiResponse, type FFIDLegalClient, type FFIDLegalClientConfig, type FFIDLegalDocument, type FFIDLegalDocumentType, type FFIDLegalError, type FFIDLegalErrorCode, type FFIDLegalLogger, type FFIDLegalSdkErrorCode, type FFIDLegalServerError, type FFIDLegalServerErrorCode, type FFIDLegalServerResponse, type FFIDPendingAgreement, type FFIDPendingAgreementsResponse, type FFIDRecordAgreementRequest, type FFIDRecordAgreementResponse, type FFIDServiceUserAgreement, FFID_LEGAL_ERROR_CODES, createFFIDLegalClient };

package/dist/legal/index.d.ts

@@ -0,0 +1,332 @@
+/**
+ * FFID SDK Shared Constants
+ *
+ * Constants shared across all SDK entry points (main client + legal client).
+ * Centralizing these prevents drift during domain/URL changes.
+ */
+/** Default FFID API base URL (production) */
+declare const DEFAULT_API_BASE_URL = "https://id.feelflow.co.jp";
+
+/**
+ * FFID Legal SDK Type Definitions
+ *
+ * Types for the FeelFlow ID Legal Document SDK.
+ * Used by external services to manage legal document agreements
+ * via Service API key authentication.
+ */
+/**
+ * Configuration for the FFID Legal Client
+ *
+ * Unlike FFIDConfig (which uses Cookie auth), this uses
+ * X-Service-Api-Key header for server-to-server communication.
+ */
+interface FFIDLegalClientConfig {
+    /** Service API key (format: ffid_sk_live_xxx or ffid_sk_test_xxx) */
+    apiKey: string;
+    /** FFID API base URL (defaults to https://id.feelflow.co.jp) */
+    apiBaseUrl?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom logger */
+    logger?: FFIDLegalLogger;
+}
+/**
+ * Logger interface for Legal SDK
+ */
+interface FFIDLegalLogger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/**
+ * Legal document types
+ */
+type FFIDLegalDocumentType = 'terms_of_service' | 'privacy_policy' | 'cookie_policy' | 'acceptable_use_policy' | 'data_processing_agreement' | 'service_level_agreement' | 'other';
+/**
+ * Agreement methods
+ */
+type FFIDAgreementMethod = 'explicit_checkbox' | 'click_through' | 'continued_use' | 'electronic_signature';
+/**
+ * Legal document returned from the API
+ */
+interface FFIDLegalDocument {
+    /** Document ID (UUID) */
+    id: string;
+    /** Document type */
+    type: FFIDLegalDocumentType;
+    /** Document title */
+    title: string;
+    /** Document version (e.g., "1.0.0") */
+    version: string;
+    /** Document content (Markdown) */
+    content: string;
+    /** Summary of the document */
+    summary: string | null;
+    /** Effective date (ISO 8601) */
+    effectiveDate: string;
+    /** Whether this document is currently active */
+    isActive: boolean;
+    /** Service scope: 'platform' or specific service ID */
+    serviceScope: string;
+    /** Whether agreement is required to use the service */
+    requiresAgreement: boolean;
+    /** SHA-256 hash of the content */
+    contentHash: string;
+    /** Created timestamp (ISO 8601) */
+    createdAt: string;
+    /** Updated timestamp (ISO 8601) */
+    updatedAt: string;
+}
+/**
+ * Service user agreement record
+ */
+interface FFIDServiceUserAgreement {
+    /** Agreement ID (UUID) */
+    id: string;
+    /** Service ID (UUID) */
+    serviceId: string;
+    /** External user ID (from the calling service) */
+    externalUserId: string;
+    /** External user email (optional) */
+    externalUserEmail: string | null;
+    /** Document ID (UUID) */
+    documentId: string;
+    /** Agreement timestamp (ISO 8601) */
+    agreedAt: string;
+    /** Method of agreement */
+    agreementMethod: FFIDAgreementMethod;
+    /** IP address at time of agreement */
+    ipAddress: string | null;
+    /** User agent at time of agreement */
+    userAgent: string | null;
+    /** Document version at time of agreement */
+    documentVersion: string;
+    /** Document title at time of agreement */
+    documentTitle: string;
+    /** Document content hash at time of agreement */
+    documentHash: string;
+    /** Additional metadata */
+    metadata: Record<string, unknown>;
+    /** Created timestamp (ISO 8601) */
+    createdAt: string;
+}
+/**
+ * Request to record an agreement
+ */
+interface FFIDRecordAgreementRequest {
+    /** External user ID (from the calling service, e.g., Google OAuth ID) */
+    externalUserId: string;
+    /** External user email (optional) */
+    externalUserEmail?: string;
+    /** Document ID to agree to */
+    documentId: string;
+    /** Method of agreement (defaults to 'click_through') */
+    agreementMethod?: FFIDAgreementMethod;
+    /** IP address of the user (if not provided, extracted from request) */
+    ipAddress?: string;
+    /** User agent of the user (if not provided, extracted from request) */
+    userAgent?: string;
+    /** Additional metadata to store with the agreement */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Response from recording an agreement
+ */
+interface FFIDRecordAgreementResponse {
+    /** Success message */
+    message: string;
+    /** Created agreement ID */
+    agreementId: string;
+    /** Document ID that was agreed to */
+    documentId: string;
+    /** External user ID */
+    externalUserId: string;
+}
+/**
+ * Agreement check result (discriminated union for type safety)
+ *
+ * When hasAgreed is true, agreement is guaranteed to be present.
+ * When hasAgreed is false, agreement is null.
+ */
+type FFIDAgreementCheckResult = {
+    hasAgreed: true;
+    agreement: FFIDServiceUserAgreement;
+} | {
+    hasAgreed: false;
+    agreement: null;
+};
+/**
+ * Pending agreement info
+ */
+interface FFIDPendingAgreement {
+    /** Document ID (UUID) */
+    documentId: string;
+    /** Document type */
+    documentType: FFIDLegalDocumentType;
+    /** Document title */
+    documentTitle: string;
+    /** Document version */
+    documentVersion: string;
+    /** Effective date (ISO 8601) */
+    effectiveDate: string;
+}
+/**
+ * Response from get pending agreements
+ */
+interface FFIDPendingAgreementsResponse {
+    /** List of pending documents */
+    pendingDocuments: FFIDPendingAgreement[];
+    /** Number of pending documents */
+    count: number;
+    /** Whether there are any pending documents */
+    hasPending: boolean;
+}
+/**
+ * Known SDK error codes (generated client-side)
+ */
+type FFIDLegalSdkErrorCode = 'MISSING_API_KEY' | 'NETWORK_ERROR' | 'PARSE_ERROR' | 'UNKNOWN_ERROR';
+/**
+ * Known server error codes (returned from FFID API)
+ */
+type FFIDLegalServerErrorCode = 'INVALID_API_KEY' | 'INSUFFICIENT_SCOPE' | 'DOCUMENT_NOT_FOUND' | 'ALREADY_AGREED' | 'VALIDATION_ERROR' | 'INTERNAL_ERROR' | 'NOT_FOUND' | 'UNAUTHORIZED' | 'FORBIDDEN';
+/**
+ * All known error codes (SDK + Server)
+ * Uses intersection with string to allow future unknown codes
+ */
+type FFIDLegalErrorCode = FFIDLegalSdkErrorCode | FFIDLegalServerErrorCode | (string & Record<never, never>);
+/**
+ * Server error details structure
+ */
+interface FFIDLegalServerError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Server response envelope from FFID Legal API (discriminated union)
+ *
+ * All API responses follow this structure with success flag as discriminator.
+ * - When success is true, data is guaranteed to be present
+ * - When success is false, error is guaranteed to be present
+ *
+ * The SDK transforms this into FFIDLegalApiResponse<T>.
+ */
+type FFIDLegalServerResponse<T> = {
+    success: true;
+    data: T;
+    error?: undefined;
+} | {
+    success: false;
+    data?: undefined;
+    error: FFIDLegalServerError;
+};
+/**
+ * Error from the Legal SDK
+ */
+interface FFIDLegalError {
+    /** Error code */
+    code: FFIDLegalErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+}
+/**
+ * API response wrapper (discriminated union for type safety)
+ *
+ * Either data is present (success) or error is present (failure), never both.
+ * This pattern ensures callers handle both cases explicitly.
+ */
+type FFIDLegalApiResponse<T> = {
+    data: T;
+    error?: undefined;
+} | {
+    data?: undefined;
+    error: FFIDLegalError;
+};
+
+/**
+ * FFID Legal API Client
+ *
+ * Handles API communication for legal document operations.
+ * Uses Service API key authentication (X-Service-Api-Key header)
+ * for server-to-server communication.
+ *
+ * @example
+ * ```typescript
+ * import { createFFIDLegalClient } from '@feelflow/ffid-sdk/legal'
+ *
+ * const legal = createFFIDLegalClient({
+ *   apiKey: process.env.FFID_SERVICE_API_KEY!,
+ * })
+ *
+ * // Get all documents
+ * const { data, error } = await legal.getDocuments()
+ *
+ * // Record agreement
+ * await legal.recordAgreement({
+ *   externalUserId: user.google_id,
+ *   documentId: doc.id,
+ * })
+ *
+ * // Check agreement
+ * const check = await legal.checkAgreement(userId, docId)
+ * ```
+ */
+
+/**
+ * Error codes used by the Legal SDK
+ */
+declare const FFID_LEGAL_ERROR_CODES: {
+    /** API key is missing */
+    readonly MISSING_API_KEY: "MISSING_API_KEY";
+    /** Network request failed (fetch threw) */
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    /** Server returned non-JSON response */
+    readonly PARSE_ERROR: "PARSE_ERROR";
+    /** Server returned error without structured error body */
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+    /** Input validation failed (empty required parameters) */
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+};
+/**
+ * Creates an FFID Legal API client instance
+ *
+ * @param config - Client configuration
+ * @returns Legal client instance
+ *
+ * @example
+ * ```typescript
+ * const legal = createFFIDLegalClient({
+ *   apiKey: process.env.FFID_SERVICE_API_KEY!,
+ *   apiBaseUrl: 'https://id.feelflow.co.jp',
+ *   debug: true,
+ * })
+ * ```
+ */
+declare function createFFIDLegalClient(config: FFIDLegalClientConfig): {
+    /** Get all legal documents available to this service */
+    getDocuments: () => Promise<FFIDLegalApiResponse<{
+        documents: FFIDLegalDocument[];
+        count: number;
+    }>>;
+    /** Get a specific legal document by ID */
+    getDocument: (documentId: string) => Promise<FFIDLegalApiResponse<{
+        document: FFIDLegalDocument;
+    }>>;
+    /** Record a user's agreement to a legal document */
+    recordAgreement: (request: FFIDRecordAgreementRequest) => Promise<FFIDLegalApiResponse<FFIDRecordAgreementResponse>>;
+    /** Check if a user has agreed to a specific document */
+    checkAgreement: (externalUserId: string, documentId: string) => Promise<FFIDLegalApiResponse<FFIDAgreementCheckResult>>;
+    /** Get all documents that a user has not yet agreed to */
+    getPendingAgreements: (externalUserId: string) => Promise<FFIDLegalApiResponse<FFIDPendingAgreementsResponse>>;
+    /** Resolved logger instance */
+    logger: FFIDLegalLogger;
+    /** API base URL */
+    baseUrl: string;
+};
+/** Type of the FFID Legal client */
+type FFIDLegalClient = ReturnType<typeof createFFIDLegalClient>;
+
+export { DEFAULT_API_BASE_URL, type FFIDAgreementCheckResult, type FFIDAgreementMethod, type FFIDLegalApiResponse, type FFIDLegalClient, type FFIDLegalClientConfig, type FFIDLegalDocument, type FFIDLegalDocumentType, type FFIDLegalError, type FFIDLegalErrorCode, type FFIDLegalLogger, type FFIDLegalSdkErrorCode, type FFIDLegalServerError, type FFIDLegalServerErrorCode, type FFIDLegalServerResponse, type FFIDPendingAgreement, type FFIDPendingAgreementsResponse, type FFIDRecordAgreementRequest, type FFIDRecordAgreementResponse, type FFIDServiceUserAgreement, FFID_LEGAL_ERROR_CODES, createFFIDLegalClient };