@revenium/openai 1.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (177) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +1095 -0
  3. package/dist/cjs/core/config/azure-config.js +64 -0
  4. package/dist/cjs/core/config/azure-config.js.map +1 -0
  5. package/dist/cjs/core/config/index.js +41 -0
  6. package/dist/cjs/core/config/index.js.map +1 -0
  7. package/dist/cjs/core/config/loader.js +63 -0
  8. package/dist/cjs/core/config/loader.js.map +1 -0
  9. package/dist/cjs/core/config/manager.js +93 -0
  10. package/dist/cjs/core/config/manager.js.map +1 -0
  11. package/dist/cjs/core/config/validator.js +73 -0
  12. package/dist/cjs/core/config/validator.js.map +1 -0
  13. package/dist/cjs/core/providers/detector.js +140 -0
  14. package/dist/cjs/core/providers/detector.js.map +1 -0
  15. package/dist/cjs/core/providers/index.js +18 -0
  16. package/dist/cjs/core/providers/index.js.map +1 -0
  17. package/dist/cjs/core/tracking/api-client.js +68 -0
  18. package/dist/cjs/core/tracking/api-client.js.map +1 -0
  19. package/dist/cjs/core/tracking/index.js +23 -0
  20. package/dist/cjs/core/tracking/index.js.map +1 -0
  21. package/dist/cjs/core/tracking/payload-builder.js +107 -0
  22. package/dist/cjs/core/tracking/payload-builder.js.map +1 -0
  23. package/dist/cjs/core/tracking/usage-tracker.js +120 -0
  24. package/dist/cjs/core/tracking/usage-tracker.js.map +1 -0
  25. package/dist/cjs/core/wrapper/index.js +15 -0
  26. package/dist/cjs/core/wrapper/index.js.map +1 -0
  27. package/dist/cjs/core/wrapper/instance-patcher.js +202 -0
  28. package/dist/cjs/core/wrapper/instance-patcher.js.map +1 -0
  29. package/dist/cjs/core/wrapper/request-handler.js +317 -0
  30. package/dist/cjs/core/wrapper/request-handler.js.map +1 -0
  31. package/dist/cjs/core/wrapper/stream-wrapper.js +82 -0
  32. package/dist/cjs/core/wrapper/stream-wrapper.js.map +1 -0
  33. package/dist/cjs/index.js +195 -0
  34. package/dist/cjs/index.js.map +1 -0
  35. package/dist/cjs/types/function-parameters.js +14 -0
  36. package/dist/cjs/types/function-parameters.js.map +1 -0
  37. package/dist/cjs/types/index.js +49 -0
  38. package/dist/cjs/types/index.js.map +1 -0
  39. package/dist/cjs/types/openai-augmentation.js +55 -0
  40. package/dist/cjs/types/openai-augmentation.js.map +1 -0
  41. package/dist/cjs/types/responses-api.js +30 -0
  42. package/dist/cjs/types/responses-api.js.map +1 -0
  43. package/dist/cjs/utils/azure-model-resolver.js +211 -0
  44. package/dist/cjs/utils/azure-model-resolver.js.map +1 -0
  45. package/dist/cjs/utils/constants.js +24 -0
  46. package/dist/cjs/utils/constants.js.map +1 -0
  47. package/dist/cjs/utils/error-handler.js +194 -0
  48. package/dist/cjs/utils/error-handler.js.map +1 -0
  49. package/dist/cjs/utils/metadata-builder.js +184 -0
  50. package/dist/cjs/utils/metadata-builder.js.map +1 -0
  51. package/dist/cjs/utils/provider-detection.js +212 -0
  52. package/dist/cjs/utils/provider-detection.js.map +1 -0
  53. package/dist/cjs/utils/request-handler-factory.js +185 -0
  54. package/dist/cjs/utils/request-handler-factory.js.map +1 -0
  55. package/dist/cjs/utils/stop-reason-mapper.js +70 -0
  56. package/dist/cjs/utils/stop-reason-mapper.js.map +1 -0
  57. package/dist/cjs/utils/type-guards.js +175 -0
  58. package/dist/cjs/utils/type-guards.js.map +1 -0
  59. package/dist/cjs/utils/url-builder.js +43 -0
  60. package/dist/cjs/utils/url-builder.js.map +1 -0
  61. package/dist/esm/core/config/azure-config.js +61 -0
  62. package/dist/esm/core/config/azure-config.js.map +1 -0
  63. package/dist/esm/core/config/index.js +13 -0
  64. package/dist/esm/core/config/index.js.map +1 -0
  65. package/dist/esm/core/config/loader.js +58 -0
  66. package/dist/esm/core/config/loader.js.map +1 -0
  67. package/dist/esm/core/config/manager.js +85 -0
  68. package/dist/esm/core/config/manager.js.map +1 -0
  69. package/dist/esm/core/config/validator.js +69 -0
  70. package/dist/esm/core/config/validator.js.map +1 -0
  71. package/dist/esm/core/providers/detector.js +134 -0
  72. package/dist/esm/core/providers/detector.js.map +1 -0
  73. package/dist/esm/core/providers/index.js +10 -0
  74. package/dist/esm/core/providers/index.js.map +1 -0
  75. package/dist/esm/core/tracking/api-client.js +65 -0
  76. package/dist/esm/core/tracking/api-client.js.map +1 -0
  77. package/dist/esm/core/tracking/index.js +13 -0
  78. package/dist/esm/core/tracking/index.js.map +1 -0
  79. package/dist/esm/core/tracking/payload-builder.js +104 -0
  80. package/dist/esm/core/tracking/payload-builder.js.map +1 -0
  81. package/dist/esm/core/tracking/usage-tracker.js +114 -0
  82. package/dist/esm/core/tracking/usage-tracker.js.map +1 -0
  83. package/dist/esm/core/wrapper/index.js +9 -0
  84. package/dist/esm/core/wrapper/index.js.map +1 -0
  85. package/dist/esm/core/wrapper/instance-patcher.js +199 -0
  86. package/dist/esm/core/wrapper/instance-patcher.js.map +1 -0
  87. package/dist/esm/core/wrapper/request-handler.js +310 -0
  88. package/dist/esm/core/wrapper/request-handler.js.map +1 -0
  89. package/dist/esm/core/wrapper/stream-wrapper.js +79 -0
  90. package/dist/esm/core/wrapper/stream-wrapper.js.map +1 -0
  91. package/dist/esm/index.js +175 -0
  92. package/dist/esm/index.js.map +1 -0
  93. package/dist/esm/types/function-parameters.js +13 -0
  94. package/dist/esm/types/function-parameters.js.map +1 -0
  95. package/dist/esm/types/index.js +32 -0
  96. package/dist/esm/types/index.js.map +1 -0
  97. package/dist/esm/types/openai-augmentation.js +54 -0
  98. package/dist/esm/types/openai-augmentation.js.map +1 -0
  99. package/dist/esm/types/responses-api.js +26 -0
  100. package/dist/esm/types/responses-api.js.map +1 -0
  101. package/dist/esm/utils/azure-model-resolver.js +204 -0
  102. package/dist/esm/utils/azure-model-resolver.js.map +1 -0
  103. package/dist/esm/utils/constants.js +21 -0
  104. package/dist/esm/utils/constants.js.map +1 -0
  105. package/dist/esm/utils/error-handler.js +182 -0
  106. package/dist/esm/utils/error-handler.js.map +1 -0
  107. package/dist/esm/utils/metadata-builder.js +176 -0
  108. package/dist/esm/utils/metadata-builder.js.map +1 -0
  109. package/dist/esm/utils/provider-detection.js +206 -0
  110. package/dist/esm/utils/provider-detection.js.map +1 -0
  111. package/dist/esm/utils/request-handler-factory.js +146 -0
  112. package/dist/esm/utils/request-handler-factory.js.map +1 -0
  113. package/dist/esm/utils/stop-reason-mapper.js +65 -0
  114. package/dist/esm/utils/stop-reason-mapper.js.map +1 -0
  115. package/dist/esm/utils/type-guards.js +158 -0
  116. package/dist/esm/utils/type-guards.js.map +1 -0
  117. package/dist/esm/utils/url-builder.js +39 -0
  118. package/dist/esm/utils/url-builder.js.map +1 -0
  119. package/dist/types/core/config/azure-config.d.ts +16 -0
  120. package/dist/types/core/config/azure-config.d.ts.map +1 -0
  121. package/dist/types/core/config/index.d.ts +11 -0
  122. package/dist/types/core/config/index.d.ts.map +1 -0
  123. package/dist/types/core/config/loader.d.ts +20 -0
  124. package/dist/types/core/config/loader.d.ts.map +1 -0
  125. package/dist/types/core/config/manager.d.ts +32 -0
  126. package/dist/types/core/config/manager.d.ts.map +1 -0
  127. package/dist/types/core/config/validator.d.ts +23 -0
  128. package/dist/types/core/config/validator.d.ts.map +1 -0
  129. package/dist/types/core/providers/detector.d.ts +44 -0
  130. package/dist/types/core/providers/detector.d.ts.map +1 -0
  131. package/dist/types/core/providers/index.d.ts +9 -0
  132. package/dist/types/core/providers/index.d.ts.map +1 -0
  133. package/dist/types/core/tracking/api-client.d.ts +17 -0
  134. package/dist/types/core/tracking/api-client.d.ts.map +1 -0
  135. package/dist/types/core/tracking/index.d.ts +11 -0
  136. package/dist/types/core/tracking/index.d.ts.map +1 -0
  137. package/dist/types/core/tracking/payload-builder.d.ts +24 -0
  138. package/dist/types/core/tracking/payload-builder.d.ts.map +1 -0
  139. package/dist/types/core/tracking/usage-tracker.d.ts +48 -0
  140. package/dist/types/core/tracking/usage-tracker.d.ts.map +1 -0
  141. package/dist/types/core/wrapper/index.d.ts +8 -0
  142. package/dist/types/core/wrapper/index.d.ts.map +1 -0
  143. package/dist/types/core/wrapper/instance-patcher.d.ts +33 -0
  144. package/dist/types/core/wrapper/instance-patcher.d.ts.map +1 -0
  145. package/dist/types/core/wrapper/request-handler.d.ts +29 -0
  146. package/dist/types/core/wrapper/request-handler.d.ts.map +1 -0
  147. package/dist/types/core/wrapper/stream-wrapper.d.ts +13 -0
  148. package/dist/types/core/wrapper/stream-wrapper.d.ts.map +1 -0
  149. package/dist/types/index.d.ts +179 -0
  150. package/dist/types/index.d.ts.map +1 -0
  151. package/dist/types/types/function-parameters.d.ts +229 -0
  152. package/dist/types/types/function-parameters.d.ts.map +1 -0
  153. package/dist/types/types/index.d.ts +283 -0
  154. package/dist/types/types/index.d.ts.map +1 -0
  155. package/dist/types/types/openai-augmentation.d.ts +226 -0
  156. package/dist/types/types/openai-augmentation.d.ts.map +1 -0
  157. package/dist/types/types/responses-api.d.ts +247 -0
  158. package/dist/types/types/responses-api.d.ts.map +1 -0
  159. package/dist/types/utils/azure-model-resolver.d.ts +41 -0
  160. package/dist/types/utils/azure-model-resolver.d.ts.map +1 -0
  161. package/dist/types/utils/constants.d.ts +4 -0
  162. package/dist/types/utils/constants.d.ts.map +1 -0
  163. package/dist/types/utils/error-handler.d.ts +95 -0
  164. package/dist/types/utils/error-handler.d.ts.map +1 -0
  165. package/dist/types/utils/metadata-builder.d.ts +64 -0
  166. package/dist/types/utils/metadata-builder.d.ts.map +1 -0
  167. package/dist/types/utils/provider-detection.d.ts +51 -0
  168. package/dist/types/utils/provider-detection.d.ts.map +1 -0
  169. package/dist/types/utils/request-handler-factory.d.ts +81 -0
  170. package/dist/types/utils/request-handler-factory.d.ts.map +1 -0
  171. package/dist/types/utils/stop-reason-mapper.d.ts +29 -0
  172. package/dist/types/utils/stop-reason-mapper.d.ts.map +1 -0
  173. package/dist/types/utils/type-guards.d.ts +73 -0
  174. package/dist/types/utils/type-guards.d.ts.map +1 -0
  175. package/dist/types/utils/url-builder.d.ts +25 -0
  176. package/dist/types/utils/url-builder.d.ts.map +1 -0
  177. package/package.json +84 -0
@@ -0,0 +1,283 @@
1
+ /**
2
+ * Core Types Module
3
+ *
4
+ * Central type definitions for the Revenium OpenAI middleware.
5
+ * This module exports all core types used throughout the application.
6
+ */
7
+ export * from './function-parameters.js';
8
+ export * from './responses-api.js';
9
+ /**
10
+ * Credential information for subscriber authentication
11
+ *
12
+ * Represents authentication credentials that can be attached to subscriber information
13
+ * for enhanced security and tracking capabilities.
14
+ *
15
+ * @public
16
+ * @example
17
+ * ```typescript
18
+ * const credential: Credential = {
19
+ * name: 'api_token',
20
+ * value: 'user_token_abc123'
21
+ * };
22
+ * ```
23
+ */
24
+ export interface Credential {
25
+ /** The name/type of the credential (e.g., 'api_token', 'session_id') */
26
+ name: string;
27
+ /** The credential value (should be handled securely) */
28
+ value: string;
29
+ }
30
+ /**
31
+ * Subscriber information for Revenium API
32
+ *
33
+ * Represents end-user information for tracking and billing purposes.
34
+ * All fields are optional to provide maximum flexibility in implementation.
35
+ *
36
+ * @public
37
+ * @example
38
+ * ```typescript
39
+ * const subscriber: Subscriber = {
40
+ * id: 'user-12345',
41
+ * email: 'john.doe@company.com',
42
+ * credential: {
43
+ * name: 'session_token',
44
+ * value: 'abc123xyz'
45
+ * }
46
+ * };
47
+ * ```
48
+ */
49
+ export interface Subscriber {
50
+ /** Unique identifier for the subscriber/user */
51
+ id?: string;
52
+ /** Email address of the subscriber */
53
+ email?: string;
54
+ /** Optional authentication credential for the subscriber */
55
+ credential?: Credential;
56
+ }
57
+ /**
58
+ * Usage metadata interface for tracking additional context
59
+ *
60
+ * Comprehensive metadata structure that enables detailed tracking of AI API usage
61
+ * for analytics, billing, and business intelligence purposes. All fields are optional
62
+ * to provide maximum flexibility while maintaining consistency across language implementations.
63
+ *
64
+ * @public
65
+ * @example
66
+ * ```typescript
67
+ * const metadata: UsageMetadata = {
68
+ * subscriber: {
69
+ * id: 'user-123',
70
+ * email: 'user@company.com'
71
+ * },
72
+ * organizationId: 'org-456',
73
+ * productId: 'chat-assistant',
74
+ * taskType: 'customer-support',
75
+ * traceId: 'trace-789',
76
+ * responseQualityScore: 0.95,
77
+ * agent: 'support-bot-v2'
78
+ * };
79
+ * ```
80
+ */
81
+ export interface UsageMetadata {
82
+ /** User identification information (nested structure for detailed tracking) */
83
+ subscriber?: Subscriber;
84
+ /** Organization or company identifier for multi-tenant applications */
85
+ organizationId?: string;
86
+ /** Product or application identifier for usage segmentation */
87
+ productId?: string;
88
+ /** Subscription identifier for billing and plan management */
89
+ subscriptionId?: string;
90
+ /** Task type classification (e.g., 'chat', 'summarization', 'translation') */
91
+ taskType?: string;
92
+ /** Unique task identifier for request correlation */
93
+ taskId?: string;
94
+ /** Distributed tracing identifier for request tracking across services */
95
+ traceId?: string;
96
+ /** Quality score for response evaluation (0.0 to 1.0) */
97
+ responseQualityScore?: number;
98
+ /** Agent or model variant identifier for A/B testing and performance tracking */
99
+ agent?: string;
100
+ /** Allow additional custom fields for extensibility */
101
+ [key: string]: unknown;
102
+ }
103
+ /**
104
+ * Provider information for tracking API source
105
+ *
106
+ * Detailed information about the detected AI provider, including configuration
107
+ * details and Azure-specific settings when applicable. Used internally for
108
+ * provider-specific handling and metrics collection.
109
+ *
110
+ * @public
111
+ * @example
112
+ * ```typescript
113
+ * const providerInfo: ProviderInfo = {
114
+ * provider: Provider.AZURE_OPENAI,
115
+ * isAzure: true,
116
+ * endpoint: 'https://my-resource.openai.azure.com',
117
+ * apiVersion: '2024-02-01',
118
+ * deployment: 'gpt-4-turbo'
119
+ * };
120
+ * ```
121
+ */
122
+ export interface ProviderInfo {
123
+ /** The detected AI provider type */
124
+ provider: Provider;
125
+ /** Whether this is an Azure OpenAI instance */
126
+ isAzure: boolean;
127
+ /** API endpoint URL (for Azure OpenAI) */
128
+ endpoint?: string;
129
+ /** API version (for Azure OpenAI) */
130
+ apiVersion?: string;
131
+ /** Deployment name (for Azure OpenAI) */
132
+ deployment?: string;
133
+ /** Complete Azure configuration when available */
134
+ azureConfig?: AzureConfig;
135
+ }
136
+ /**
137
+ * Supported AI providers
138
+ *
139
+ * Enumeration of AI providers supported by the Revenium middleware.
140
+ * Used for automatic detection, routing, and provider-specific handling.
141
+ *
142
+ * @public
143
+ * @example
144
+ * ```typescript
145
+ * if (providerInfo.provider === Provider.AZURE_OPENAI) {
146
+ * console.log('Using Azure OpenAI');
147
+ * }
148
+ * ```
149
+ */
150
+ export declare enum Provider {
151
+ /** Standard OpenAI API */
152
+ OPENAI = "OPENAI",
153
+ /** Azure OpenAI Service */
154
+ AZURE_OPENAI = "AZURE_OPENAI"
155
+ }
156
+ /**
157
+ * Azure OpenAI configuration
158
+ *
159
+ * Configuration interface for Azure OpenAI Service integration.
160
+ * Provides all necessary settings for connecting to Azure OpenAI endpoints
161
+ * with proper authentication and resource identification.
162
+ *
163
+ * @public
164
+ * @example
165
+ * ```typescript
166
+ * const azureConfig: AzureConfig = {
167
+ * endpoint: 'https://my-resource.openai.azure.com',
168
+ * apiKey: process.env.AZURE_OPENAI_API_KEY,
169
+ * apiVersion: '2024-02-01',
170
+ * deployment: 'gpt-4-turbo',
171
+ * tenantId: 'your-tenant-id'
172
+ * };
173
+ * ```
174
+ */
175
+ export interface AzureConfig {
176
+ /** Azure OpenAI endpoint URL */
177
+ endpoint?: string;
178
+ /** Azure OpenAI API key */
179
+ apiKey?: string;
180
+ /** Azure OpenAI API version */
181
+ apiVersion?: string;
182
+ /** Azure OpenAI deployment name */
183
+ deployment?: string;
184
+ /** Azure tenant ID for authentication */
185
+ tenantId?: string;
186
+ /** Azure resource group name */
187
+ resourceGroup?: string;
188
+ }
189
+ /**
190
+ * Revenium configuration interface
191
+ *
192
+ * Main configuration interface for initializing the Revenium middleware.
193
+ * Defines all required and optional settings for connecting to Revenium's
194
+ * metering API and configuring middleware behavior.
195
+ *
196
+ * @public
197
+ * @example
198
+ * ```typescript
199
+ * const config: ReveniumConfig = {
200
+ * reveniumApiKey: 'hak_your_revenium_api_key',
201
+ * reveniumBaseUrl: 'https://api.revenium.io/meter',
202
+ * debug: true,
203
+ * openaiApiKey: process.env.OPENAI_API_KEY
204
+ * };
205
+ * ```
206
+ */
207
+ export interface ReveniumConfig {
208
+ /** Revenium API key for authentication (required) */
209
+ reveniumApiKey: string;
210
+ /** Revenium API base URL (optional, defaults to https://api.revenium.io/meter) */
211
+ reveniumBaseUrl?: string;
212
+ /** Enable debug logging (optional, defaults to false) */
213
+ debug?: boolean;
214
+ /** Azure OpenAI configuration (optional, for Azure OpenAI usage) */
215
+ azure?: AzureConfig;
216
+ /** OpenAI API key (optional, can be set via environment variable) */
217
+ openaiApiKey?: string;
218
+ }
219
+ /**
220
+ * Logger interface for consistent logging
221
+ *
222
+ * Standardized logging interface that allows custom logger integration
223
+ * while maintaining consistent log levels and metadata support throughout
224
+ * the middleware. Supports both structured and string metadata.
225
+ *
226
+ * @public
227
+ * @example
228
+ * ```typescript
229
+ * const customLogger: Logger = {
230
+ * debug: (msg, meta) => console.debug(`[DEBUG] ${msg}`, meta),
231
+ * info: (msg, meta) => console.info(`[INFO] ${msg}`, meta),
232
+ * warn: (msg, meta) => console.warn(`[WARN] ${msg}`, meta),
233
+ * error: (msg, meta) => console.error(`[ERROR] ${msg}`, meta)
234
+ * };
235
+ * ```
236
+ */
237
+ export interface Logger {
238
+ /** Log debug-level messages with optional metadata */
239
+ debug(message: string, meta?: Record<string, unknown> | string): void;
240
+ /** Log info-level messages with optional metadata */
241
+ info(message: string, meta?: Record<string, unknown> | string): void;
242
+ /** Log warning-level messages with optional metadata */
243
+ warn(message: string, meta?: Record<string, unknown> | string): void;
244
+ /** Log error-level messages with optional metadata */
245
+ error(message: string, meta?: Record<string, unknown> | string | unknown): void;
246
+ }
247
+ /**
248
+ * Revenium API payload structure
249
+ */
250
+ export interface ReveniumPayload {
251
+ transactionId: string;
252
+ operationType: 'CHAT' | 'EMBED';
253
+ costType: 'AI';
254
+ model: string;
255
+ provider: string;
256
+ modelSource?: string;
257
+ middlewareSource: string;
258
+ requestTime: string;
259
+ responseTime: string;
260
+ requestDuration: number;
261
+ completionStartTime: string;
262
+ inputTokenCount: number;
263
+ outputTokenCount: number;
264
+ totalTokenCount: number;
265
+ reasoningTokenCount: number;
266
+ cacheCreationTokenCount: number;
267
+ cacheReadTokenCount: number;
268
+ stopReason: string;
269
+ isStreamed: boolean;
270
+ timeToFirstToken?: number;
271
+ inputTokenCost?: number;
272
+ outputTokenCost?: number;
273
+ totalCost?: number;
274
+ traceId?: string;
275
+ taskType?: string;
276
+ agent?: string;
277
+ organizationId?: string;
278
+ productId?: string;
279
+ subscriber?: Subscriber;
280
+ subscriptionId?: string;
281
+ responseQualityScore?: number;
282
+ }
283
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,226 @@
1
+ /**
2
+ * TypeScript module augmentation for OpenAI SDK
3
+ *
4
+ * This file extends OpenAI's existing types to include the usageMetadata field
5
+ * through TypeScript's declaration merging feature. This provides seamless
6
+ * integration with the OpenAI SDK, allowing developers to use usageMetadata
7
+ * directly in OpenAI API calls without type casting or additional imports.
8
+ *
9
+ * The augmentation covers all major OpenAI API endpoints including:
10
+ * - Chat completions (streaming and non-streaming)
11
+ * - Embeddings
12
+ * - Future API endpoints as they become available
13
+ *
14
+ * @fileoverview OpenAI SDK type augmentation for Revenium middleware
15
+ * @author Revenium
16
+ * @since 1.0.0
17
+ *
18
+ * @example Basic usage with chat completions
19
+ * ```typescript
20
+ * import 'revenium-middleware-openai-node';
21
+ * import OpenAI from 'openai';
22
+ *
23
+ * const openai = new OpenAI();
24
+ *
25
+ * const response = await openai.chat.completions.create({
26
+ * model: 'gpt-4o-mini',
27
+ * messages: [{ role: 'user', content: 'Hello!' }],
28
+ * usageMetadata: { // TypeScript recognizes this natively
29
+ * subscriber: {
30
+ * id: 'user-123',
31
+ * email: 'user@my-company.com'
32
+ * },
33
+ * organizationId: 'my-company',
34
+ * productId: 'chat-app',
35
+ * taskType: 'customer-support'
36
+ * }
37
+ * });
38
+ * ```
39
+ *
40
+ * @example Usage with embeddings
41
+ * ```typescript
42
+ * const embedding = await openai.embeddings.create({
43
+ * model: 'text-embedding-ada-002',
44
+ * input: 'Text to embed',
45
+ * usageMetadata: {
46
+ * subscriber: { id: 'user-456' },
47
+ * productId: 'search-engine',
48
+ * taskType: 'document-indexing'
49
+ * }
50
+ * });
51
+ * ```
52
+ */
53
+ import { UsageMetadata } from './index.js';
54
+ export {};
55
+ /**
56
+ * OpenAI Chat Completions API augmentation
57
+ *
58
+ * Extends the OpenAI chat completions interfaces to include usageMetadata
59
+ * for all completion types (base, streaming, and non-streaming).
60
+ */
61
+ declare module 'openai/resources/chat/completions/completions' {
62
+ interface ChatCompletionCreateParamsBase {
63
+ /**
64
+ * Optional metadata for enhanced tracking and analytics.
65
+ *
66
+ * Provides rich context for business analytics, user tracking, and billing purposes.
67
+ * All fields are optional to maintain backward compatibility and provide maximum flexibility.
68
+ *
69
+ * This metadata is automatically captured by the Revenium middleware and sent to
70
+ * the Revenium API for detailed usage analytics and billing calculations.
71
+ *
72
+ * @since 1.0.0
73
+ * @example Basic user tracking
74
+ * ```typescript
75
+ * usageMetadata: {
76
+ * subscriber: {
77
+ * id: 'user-123',
78
+ * email: 'user@my-company.com'
79
+ * },
80
+ * organizationId: 'my-company',
81
+ * productId: 'support-app'
82
+ * }
83
+ * ```
84
+ *
85
+ * @example Advanced tracking with quality metrics
86
+ * ```typescript
87
+ * usageMetadata: {
88
+ * subscriber: { id: 'user-456' },
89
+ * organizationId: 'enterprise-corp',
90
+ * productId: 'ai-assistant',
91
+ * taskType: 'customer-support',
92
+ * traceId: 'session-abc-123',
93
+ * responseQualityScore: 0.95,
94
+ * agent: 'support-bot-v2'
95
+ * }
96
+ * ```
97
+ */
98
+ usageMetadata?: UsageMetadata;
99
+ }
100
+ interface ChatCompletionCreateParamsNonStreaming {
101
+ /**
102
+ * Optional metadata for enhanced tracking and analytics.
103
+ *
104
+ * Provides rich context for business analytics, user tracking, and billing purposes.
105
+ * Specifically for non-streaming chat completions where the full response is returned at once.
106
+ *
107
+ * @see {@link UsageMetadata} for detailed field descriptions
108
+ */
109
+ usageMetadata?: UsageMetadata;
110
+ }
111
+ interface ChatCompletionCreateParamsStreaming {
112
+ /**
113
+ * Optional metadata for enhanced tracking and analytics.
114
+ *
115
+ * Provides rich context for business analytics, user tracking, and billing purposes.
116
+ * Specifically for streaming chat completions where the response is delivered incrementally.
117
+ *
118
+ * @see {@link UsageMetadata} for detailed field descriptions
119
+ */
120
+ usageMetadata?: UsageMetadata;
121
+ }
122
+ }
123
+ /**
124
+ * OpenAI Embeddings API augmentation
125
+ *
126
+ * Extends the OpenAI embeddings interface to include usageMetadata
127
+ * for comprehensive tracking of embedding generation requests.
128
+ */
129
+ declare module 'openai/resources/embeddings' {
130
+ interface EmbeddingCreateParams {
131
+ /**
132
+ * Optional metadata for enhanced tracking and analytics.
133
+ *
134
+ * Provides rich context for business analytics, user tracking, and billing purposes
135
+ * specifically for embedding generation requests. Particularly useful for tracking
136
+ * vector database operations, search functionality, and document processing workflows.
137
+ *
138
+ * All fields are optional to maintain backward compatibility and provide maximum flexibility.
139
+ *
140
+ * @since 1.0.0
141
+ * @example Document indexing workflow
142
+ * ```typescript
143
+ * usageMetadata: {
144
+ * subscriber: {
145
+ * id: 'user-123',
146
+ * email: 'user@my-company.com'
147
+ * },
148
+ * organizationId: 'my-company',
149
+ * productId: 'vector-search',
150
+ * taskType: 'document-indexing',
151
+ * taskId: 'batch-index-2024-01'
152
+ * }
153
+ * ```
154
+ *
155
+ * @example Semantic search application
156
+ * ```typescript
157
+ * usageMetadata: {
158
+ * subscriber: { id: 'user-456' },
159
+ * organizationId: 'enterprise-corp',
160
+ * productId: 'knowledge-base',
161
+ * taskType: 'semantic-search',
162
+ * traceId: 'search-session-789'
163
+ * }
164
+ * ```
165
+ *
166
+ * @see {@link UsageMetadata} for detailed field descriptions
167
+ */
168
+ usageMetadata?: UsageMetadata;
169
+ }
170
+ }
171
+ /**
172
+ * OpenAI Responses API augmentation
173
+ *
174
+ * Extends the new Responses API to support usageMetadata for comprehensive tracking.
175
+ * The Responses API is OpenAI's new unified interface for agent-like applications.
176
+ */
177
+ declare module 'openai' {
178
+ namespace Responses {
179
+ interface ResponseCreateParams {
180
+ /**
181
+ * Custom usage metadata for Revenium tracking
182
+ *
183
+ * Enables comprehensive tracking and analytics for Responses API calls.
184
+ * All fields are optional and can be customized based on your application needs.
185
+ *
186
+ * @example Basic Responses API usage with metadata
187
+ * ```typescript
188
+ * const response = await openai.responses.create({
189
+ * model: 'gpt-4.1',
190
+ * input: 'Analyze this data and provide insights',
191
+ * usageMetadata: {
192
+ * subscriber: {
193
+ * id: 'analyst-123',
194
+ * email: 'analyst@company.com'
195
+ * },
196
+ * organizationId: 'data-corp',
197
+ * productId: 'analytics-platform',
198
+ * taskType: 'data-analysis',
199
+ * agent: 'responses-api-v1'
200
+ * }
201
+ * });
202
+ * ```
203
+ *
204
+ * @example Streaming Responses API with metadata
205
+ * ```typescript
206
+ * const stream = await openai.responses.create({
207
+ * model: 'gpt-4.1',
208
+ * input: [
209
+ * { role: 'user', content: 'Generate a detailed report' }
210
+ * ],
211
+ * stream: true,
212
+ * usageMetadata: {
213
+ * subscriber: { id: 'user-456' },
214
+ * taskType: 'report-generation',
215
+ * traceId: 'session-789'
216
+ * }
217
+ * });
218
+ * ```
219
+ *
220
+ * @see {@link UsageMetadata} for detailed field descriptions
221
+ */
222
+ usageMetadata?: UsageMetadata;
223
+ }
224
+ }
225
+ }
226
+ //# sourceMappingURL=openai-augmentation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"openai-augmentation.d.ts","sourceRoot":"","sources":["../../../src/types/openai-augmentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3C,OAAO,EAAE,CAAC;AAEV;;;;;GAKG;AACH,OAAO,QAAQ,+CAA+C,CAAC;IAC7D,UAAU,8BAA8B;QACtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAkCG;QACH,aAAa,CAAC,EAAE,aAAa,CAAC;KAC/B;IAED,UAAU,sCAAsC;QAC9C;;;;;;;WAOG;QACH,aAAa,CAAC,EAAE,aAAa,CAAC;KAC/B;IAED,UAAU,mCAAmC;QAC3C;;;;;;;WAOG;QACH,aAAa,CAAC,EAAE,aAAa,CAAC;KAC/B;CACF;AAED;;;;;GAKG;AACH,OAAO,QAAQ,6BAA6B,CAAC;IAC3C,UAAU,qBAAqB;QAC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAoCG;QACH,aAAa,CAAC,EAAE,aAAa,CAAC;KAC/B;CACF;AAED;;;;;GAKG;AACH,OAAO,QAAQ,QAAQ,CAAC;IACtB,UAAU,SAAS,CAAC;QAClB,UAAU,oBAAoB;YAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAyCG;YACH,aAAa,CAAC,EAAE,aAAa,CAAC;SAC/B;KACF;CACF"}