optropic 2.3.0 → 3.0.0
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.
- package/dist/index.cjs +2105 -2
- package/dist/index.d.cts +2824 -14
- package/dist/index.d.ts +2824 -14
- package/dist/index.js +2027 -2
- package/package.json +5 -3
package/dist/index.d.cts
CHANGED
|
@@ -77,6 +77,157 @@ interface RetryConfig {
|
|
|
77
77
|
* Use these for programmatic error handling.
|
|
78
78
|
*/
|
|
79
79
|
type ErrorCode = 'INVALID_API_KEY' | 'EXPIRED_API_KEY' | 'INSUFFICIENT_PERMISSIONS' | 'INVALID_GTIN' | 'INVALID_SERIAL' | 'INVALID_CODE_FORMAT' | 'INVALID_BATCH_CONFIG' | 'CODE_NOT_FOUND' | 'BATCH_NOT_FOUND' | 'PRODUCT_NOT_FOUND' | 'CODE_REVOKED' | 'CODE_EXPIRED' | 'BATCH_ALREADY_EXISTS' | 'RATE_LIMITED' | 'QUOTA_EXCEEDED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'SERVICE_UNAVAILABLE' | 'INTERNAL_ERROR' | 'UNKNOWN_ERROR';
|
|
80
|
+
/**
|
|
81
|
+
* Type-safe permission constants for API key creation.
|
|
82
|
+
*
|
|
83
|
+
* @example
|
|
84
|
+
* ```typescript
|
|
85
|
+
* import { Permission } from 'optropic';
|
|
86
|
+
*
|
|
87
|
+
* const key = await client.keys.create({
|
|
88
|
+
* environment: 'live',
|
|
89
|
+
* label: 'Read-only integration',
|
|
90
|
+
* permissions: [Permission.ASSETS_READ, Permission.ASSETS_VERIFY],
|
|
91
|
+
* });
|
|
92
|
+
* ```
|
|
93
|
+
*/
|
|
94
|
+
declare const Permission: {
|
|
95
|
+
readonly ASSETS_READ: "assets:read";
|
|
96
|
+
readonly ASSETS_WRITE: "assets:write";
|
|
97
|
+
readonly ASSETS_VERIFY: "assets:verify";
|
|
98
|
+
readonly AUDIT_READ: "audit:read";
|
|
99
|
+
readonly COMPLIANCE_READ: "compliance:read";
|
|
100
|
+
readonly KEYS_MANAGE: "keys:manage";
|
|
101
|
+
readonly SCHEMAS_MANAGE: "schemas:manage";
|
|
102
|
+
readonly DOCUMENTS_ENROLL: "documents:enroll";
|
|
103
|
+
readonly DOCUMENTS_VERIFY: "documents:verify";
|
|
104
|
+
readonly PROVENANCE_READ: "provenance:read";
|
|
105
|
+
readonly PROVENANCE_WRITE: "provenance:write";
|
|
106
|
+
readonly WEBHOOKS_MANAGE: "webhooks:manage";
|
|
107
|
+
/** All read permissions. */
|
|
108
|
+
readonly ALL_READ: readonly ["assets:read", "audit:read", "compliance:read", "provenance:read"];
|
|
109
|
+
/** All write permissions. */
|
|
110
|
+
readonly ALL_WRITE: readonly ["assets:write", "assets:verify", "documents:enroll", "documents:verify", "provenance:write", "webhooks:manage", "keys:manage", "schemas:manage"];
|
|
111
|
+
/** All permissions combined. */
|
|
112
|
+
readonly all: () => string[];
|
|
113
|
+
};
|
|
114
|
+
type PermissionValue = typeof Permission[keyof Omit<typeof Permission, 'ALL_READ' | 'ALL_WRITE' | 'all'>];
|
|
115
|
+
/**
|
|
116
|
+
* Rate limit status parsed from response headers.
|
|
117
|
+
* Updated automatically after every API call.
|
|
118
|
+
*/
|
|
119
|
+
interface RateLimitInfo {
|
|
120
|
+
/** Maximum requests allowed per period. */
|
|
121
|
+
readonly limit: number;
|
|
122
|
+
/** Remaining requests in current period. */
|
|
123
|
+
readonly remaining: number;
|
|
124
|
+
/** ISO 8601 timestamp when the limit resets. */
|
|
125
|
+
readonly reset?: string;
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Current tenant information.
|
|
129
|
+
*/
|
|
130
|
+
interface Tenant {
|
|
131
|
+
readonly id: string;
|
|
132
|
+
readonly name: string;
|
|
133
|
+
readonly plan: string;
|
|
134
|
+
readonly status: 'active' | 'suspended' | 'cancelled';
|
|
135
|
+
readonly createdAt: string;
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* Tenant resource limits based on plan.
|
|
139
|
+
*/
|
|
140
|
+
interface TenantLimits {
|
|
141
|
+
readonly maxAssets: number;
|
|
142
|
+
readonly maxApiCallsPerMonth: number;
|
|
143
|
+
readonly maxKeys: number;
|
|
144
|
+
readonly maxWebhooks: number;
|
|
145
|
+
readonly maxBatchSize: number;
|
|
146
|
+
}
|
|
147
|
+
/**
|
|
148
|
+
* Usage metrics for a given period.
|
|
149
|
+
*/
|
|
150
|
+
interface UsageReport {
|
|
151
|
+
readonly apiCalls: number;
|
|
152
|
+
readonly assetsCreated: number;
|
|
153
|
+
readonly verifications: number;
|
|
154
|
+
readonly documentsEnrolled: number;
|
|
155
|
+
readonly bandwidthMb: number;
|
|
156
|
+
readonly periodStart: string;
|
|
157
|
+
readonly periodEnd: string;
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* Endpoint-level usage breakdown.
|
|
161
|
+
*/
|
|
162
|
+
interface EndpointUsage {
|
|
163
|
+
readonly endpoint: string;
|
|
164
|
+
readonly calls: number;
|
|
165
|
+
readonly errors: number;
|
|
166
|
+
readonly avgLatencyMs: number;
|
|
167
|
+
readonly bandwidthMb: number;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* Quota information for the current API key.
|
|
171
|
+
*/
|
|
172
|
+
interface QuotaInfo {
|
|
173
|
+
readonly limit: number;
|
|
174
|
+
readonly remaining: number;
|
|
175
|
+
readonly reset?: string;
|
|
176
|
+
readonly resetAt?: string;
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* Batch job information.
|
|
180
|
+
*/
|
|
181
|
+
interface BatchJob {
|
|
182
|
+
readonly batchId: string;
|
|
183
|
+
readonly operation: string;
|
|
184
|
+
readonly status: 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
|
|
185
|
+
readonly progress: number;
|
|
186
|
+
readonly createdAt: string;
|
|
187
|
+
readonly completedAt?: string;
|
|
188
|
+
readonly totalItems: number;
|
|
189
|
+
readonly processedItems: number;
|
|
190
|
+
readonly failedItems: number;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* Result of a completed batch operation.
|
|
194
|
+
*/
|
|
195
|
+
interface BatchResult {
|
|
196
|
+
readonly batchId: string;
|
|
197
|
+
readonly operation: string;
|
|
198
|
+
readonly status: 'completed' | 'failed' | 'cancelled';
|
|
199
|
+
readonly totalItems: number;
|
|
200
|
+
readonly processedItems: number;
|
|
201
|
+
readonly failedItems: number;
|
|
202
|
+
readonly completedAt: string;
|
|
203
|
+
readonly results?: unknown[];
|
|
204
|
+
readonly errors?: Array<{
|
|
205
|
+
readonly index: number;
|
|
206
|
+
readonly error: string;
|
|
207
|
+
}>;
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* Information about a specific API key.
|
|
211
|
+
*/
|
|
212
|
+
interface KeyInfo {
|
|
213
|
+
readonly keyId: string;
|
|
214
|
+
readonly name: string;
|
|
215
|
+
readonly permissions: string[];
|
|
216
|
+
readonly rateLimit: number;
|
|
217
|
+
readonly expiresAt?: string;
|
|
218
|
+
readonly lastUsedAt?: string;
|
|
219
|
+
readonly allowedIps?: string[];
|
|
220
|
+
}
|
|
221
|
+
/**
|
|
222
|
+
* Result of rotating an API key.
|
|
223
|
+
*/
|
|
224
|
+
interface RotateKeyResult {
|
|
225
|
+
readonly oldKeyId: string;
|
|
226
|
+
readonly newKeyId: string;
|
|
227
|
+
readonly newKey: string;
|
|
228
|
+
readonly newPrefix: string;
|
|
229
|
+
readonly gracePeriodUntil?: string;
|
|
230
|
+
}
|
|
80
231
|
|
|
81
232
|
/**
|
|
82
233
|
* Assets Resource
|
|
@@ -152,6 +303,31 @@ interface BatchCreateResult {
|
|
|
152
303
|
readonly requested: number;
|
|
153
304
|
readonly assets: Asset[];
|
|
154
305
|
}
|
|
306
|
+
interface BatchVerifyResult {
|
|
307
|
+
readonly verified: number;
|
|
308
|
+
readonly requested: number;
|
|
309
|
+
readonly results: Array<{
|
|
310
|
+
readonly assetId: string;
|
|
311
|
+
readonly signatureValid: boolean;
|
|
312
|
+
readonly revocationStatus: string;
|
|
313
|
+
}>;
|
|
314
|
+
readonly errors?: Array<{
|
|
315
|
+
readonly assetId: string;
|
|
316
|
+
readonly error: string;
|
|
317
|
+
}>;
|
|
318
|
+
}
|
|
319
|
+
interface BatchRevokeResult {
|
|
320
|
+
readonly revoked: number;
|
|
321
|
+
readonly requested: number;
|
|
322
|
+
readonly results: Array<{
|
|
323
|
+
readonly assetId: string;
|
|
324
|
+
readonly status: string;
|
|
325
|
+
}>;
|
|
326
|
+
readonly errors?: Array<{
|
|
327
|
+
readonly assetId: string;
|
|
328
|
+
readonly error: string;
|
|
329
|
+
}>;
|
|
330
|
+
}
|
|
155
331
|
declare class AssetsResource {
|
|
156
332
|
private readonly request;
|
|
157
333
|
private readonly client;
|
|
@@ -181,6 +357,8 @@ declare class AssetsResource {
|
|
|
181
357
|
verify(assetId: string): Promise<VerifyResult>;
|
|
182
358
|
revoke(assetId: string, reason?: string): Promise<Asset>;
|
|
183
359
|
batchCreate(params: BatchCreateParams): Promise<BatchCreateResult>;
|
|
360
|
+
batchVerify(assetIds: string[]): Promise<BatchVerifyResult>;
|
|
361
|
+
batchRevoke(assetIds: string[], reason: string): Promise<BatchRevokeResult>;
|
|
184
362
|
private buildQuery;
|
|
185
363
|
}
|
|
186
364
|
|
|
@@ -244,6 +422,55 @@ declare class AuditResource {
|
|
|
244
422
|
private buildQuery;
|
|
245
423
|
}
|
|
246
424
|
|
|
425
|
+
/**
|
|
426
|
+
* Batches Resource
|
|
427
|
+
*
|
|
428
|
+
* Batch job operations for bulk processing.
|
|
429
|
+
*/
|
|
430
|
+
|
|
431
|
+
interface CreateBatchParams {
|
|
432
|
+
readonly operation: string;
|
|
433
|
+
readonly items: unknown[];
|
|
434
|
+
}
|
|
435
|
+
interface ListBatchesParams {
|
|
436
|
+
readonly limit?: number;
|
|
437
|
+
}
|
|
438
|
+
interface WaitOptions {
|
|
439
|
+
readonly pollInterval?: number;
|
|
440
|
+
readonly timeout?: number;
|
|
441
|
+
}
|
|
442
|
+
declare class BatchesResource {
|
|
443
|
+
private readonly request;
|
|
444
|
+
constructor(request: RequestFn);
|
|
445
|
+
/**
|
|
446
|
+
* Create a new batch job with the given operation and items.
|
|
447
|
+
*/
|
|
448
|
+
create(params: CreateBatchParams): Promise<BatchJob>;
|
|
449
|
+
/**
|
|
450
|
+
* Get the status and details of a specific batch job.
|
|
451
|
+
*/
|
|
452
|
+
get(batchId: string): Promise<BatchJob>;
|
|
453
|
+
/**
|
|
454
|
+
* List batch jobs with optional limiting.
|
|
455
|
+
*/
|
|
456
|
+
list(params?: ListBatchesParams): Promise<BatchJob[]>;
|
|
457
|
+
/**
|
|
458
|
+
* Wait for a batch job to complete, polling at regular intervals.
|
|
459
|
+
*
|
|
460
|
+
* @param batchId - The ID of the batch to wait for
|
|
461
|
+
* @param opts - Polling configuration (pollInterval in ms, timeout in ms)
|
|
462
|
+
* @returns The final batch result once completed
|
|
463
|
+
* @throws TimeoutError if the operation exceeds the timeout
|
|
464
|
+
*/
|
|
465
|
+
wait(batchId: string, opts?: WaitOptions): Promise<BatchResult>;
|
|
466
|
+
/**
|
|
467
|
+
* Cancel a batch job that is still pending or processing.
|
|
468
|
+
*/
|
|
469
|
+
cancel(batchId: string): Promise<BatchJob>;
|
|
470
|
+
private buildQuery;
|
|
471
|
+
private sleep;
|
|
472
|
+
}
|
|
473
|
+
|
|
247
474
|
/**
|
|
248
475
|
* Compliance Resource
|
|
249
476
|
*
|
|
@@ -448,6 +675,9 @@ interface ApiKey {
|
|
|
448
675
|
interface CreateKeyParams {
|
|
449
676
|
readonly label?: string;
|
|
450
677
|
readonly environment?: 'live' | 'test';
|
|
678
|
+
readonly expiresInDays?: number;
|
|
679
|
+
readonly rateLimitPerMinute?: number;
|
|
680
|
+
readonly allowedIps?: string[];
|
|
451
681
|
}
|
|
452
682
|
interface CreateKeyResult {
|
|
453
683
|
readonly key: string;
|
|
@@ -457,12 +687,27 @@ interface CreateKeyResult {
|
|
|
457
687
|
readonly environment: string;
|
|
458
688
|
readonly created_at: string;
|
|
459
689
|
}
|
|
690
|
+
interface RotateKeyParams {
|
|
691
|
+
readonly gracePeriodHours?: number;
|
|
692
|
+
}
|
|
460
693
|
declare class KeysResource {
|
|
461
694
|
private readonly request;
|
|
462
695
|
constructor(request: RequestFn);
|
|
463
696
|
create(params?: CreateKeyParams): Promise<CreateKeyResult>;
|
|
464
697
|
list(): Promise<ApiKey[]>;
|
|
465
698
|
revoke(keyId: string): Promise<void>;
|
|
699
|
+
/**
|
|
700
|
+
* Get information about the current API key being used.
|
|
701
|
+
*/
|
|
702
|
+
current(): Promise<KeyInfo>;
|
|
703
|
+
/**
|
|
704
|
+
* Rotate the specified API key to a new one.
|
|
705
|
+
*
|
|
706
|
+
* @param keyId - The ID of the key to rotate
|
|
707
|
+
* @param opts - Optional rotation parameters (gracePeriodHours)
|
|
708
|
+
* @returns New key information and the new key string
|
|
709
|
+
*/
|
|
710
|
+
rotate(keyId: string, opts?: RotateKeyParams): Promise<RotateKeyResult>;
|
|
466
711
|
}
|
|
467
712
|
|
|
468
713
|
/**
|
|
@@ -503,6 +748,311 @@ declare class KeysetsResource {
|
|
|
503
748
|
private buildQuery;
|
|
504
749
|
}
|
|
505
750
|
|
|
751
|
+
/**
|
|
752
|
+
* M2M Ed25519 Audit Trail
|
|
753
|
+
*
|
|
754
|
+
* Append-only signed audit records for M2M verification events.
|
|
755
|
+
*/
|
|
756
|
+
type AuditRecordType = 'challenge_issued' | 'challenge_responded' | 'consensus_established' | 'consensus_denied' | 'device_registered' | 'device_revoked';
|
|
757
|
+
interface AuditRecord {
|
|
758
|
+
id: string;
|
|
759
|
+
type: AuditRecordType;
|
|
760
|
+
assetId: string;
|
|
761
|
+
deviceIds: string[];
|
|
762
|
+
timestamp: string;
|
|
763
|
+
previousHash: string;
|
|
764
|
+
data: Record<string, unknown>;
|
|
765
|
+
hash: string;
|
|
766
|
+
signature?: string;
|
|
767
|
+
}
|
|
768
|
+
interface AuditChain {
|
|
769
|
+
records: AuditRecord[];
|
|
770
|
+
chainId: string;
|
|
771
|
+
createdAt: string;
|
|
772
|
+
lastHash: string;
|
|
773
|
+
}
|
|
774
|
+
/**
|
|
775
|
+
* Create a new audit chain
|
|
776
|
+
*/
|
|
777
|
+
declare function createAuditChain(chainId?: string): AuditChain;
|
|
778
|
+
/**
|
|
779
|
+
* Append a record to an audit chain
|
|
780
|
+
*/
|
|
781
|
+
declare function appendRecord(chain: AuditChain, type: AuditRecordType, assetId: string, deviceIds: string[], data: Record<string, unknown>): Promise<AuditRecord>;
|
|
782
|
+
/**
|
|
783
|
+
* Verify the integrity of an audit chain
|
|
784
|
+
*/
|
|
785
|
+
declare function verifyChain(chain: AuditChain): Promise<{
|
|
786
|
+
valid: boolean;
|
|
787
|
+
brokenAt?: number;
|
|
788
|
+
error?: string;
|
|
789
|
+
}>;
|
|
790
|
+
/**
|
|
791
|
+
* Export audit chain to JSON string
|
|
792
|
+
*/
|
|
793
|
+
declare function exportChain(chain: AuditChain): string;
|
|
794
|
+
/**
|
|
795
|
+
* Import audit chain from JSON string
|
|
796
|
+
*/
|
|
797
|
+
declare function importChain(data: string): Promise<AuditChain>;
|
|
798
|
+
|
|
799
|
+
/**
|
|
800
|
+
* M2M Consensus Engine
|
|
801
|
+
*
|
|
802
|
+
* Core of Optropic's "Sovereign Physical Handshake".
|
|
803
|
+
* Two independent devices scan the same physical object and derive descriptors.
|
|
804
|
+
* The consensus engine determines if they match.
|
|
805
|
+
*/
|
|
806
|
+
interface CaptureConditions {
|
|
807
|
+
lightLevel?: 'low' | 'medium' | 'high';
|
|
808
|
+
distance?: number;
|
|
809
|
+
angle?: number;
|
|
810
|
+
}
|
|
811
|
+
interface PhysicalDescriptor {
|
|
812
|
+
dimensions: number[];
|
|
813
|
+
deviceId: string;
|
|
814
|
+
timestamp: string;
|
|
815
|
+
captureConditions?: CaptureConditions;
|
|
816
|
+
}
|
|
817
|
+
interface DimensionMatch {
|
|
818
|
+
dimension: number;
|
|
819
|
+
delta: number;
|
|
820
|
+
withinTolerance: boolean;
|
|
821
|
+
}
|
|
822
|
+
interface ConsensusResult {
|
|
823
|
+
trustEstablished: boolean;
|
|
824
|
+
confidence: number;
|
|
825
|
+
distance: number;
|
|
826
|
+
threshold: number;
|
|
827
|
+
descriptorDimensions: number;
|
|
828
|
+
matchDetails: DimensionMatch[];
|
|
829
|
+
auditToken: string;
|
|
830
|
+
timestamp: string;
|
|
831
|
+
}
|
|
832
|
+
interface ConsensusConfig {
|
|
833
|
+
threshold?: number;
|
|
834
|
+
minDimensions?: number;
|
|
835
|
+
maxTimeDeltaMs?: number;
|
|
836
|
+
requireAllDimensions?: boolean;
|
|
837
|
+
}
|
|
838
|
+
/**
|
|
839
|
+
* Compute Euclidean distance between two vectors
|
|
840
|
+
*/
|
|
841
|
+
declare function computeDistance(a: number[], b: number[]): number;
|
|
842
|
+
/**
|
|
843
|
+
* Compute similarity score (1 / (1 + distance))
|
|
844
|
+
*/
|
|
845
|
+
declare function computeSimilarity(a: number[], b: number[]): number;
|
|
846
|
+
/**
|
|
847
|
+
* Calibrate threshold using ROC analysis on labeled pairs
|
|
848
|
+
*
|
|
849
|
+
* @param knownMatches - Array of {a, b, isMatch} pairs
|
|
850
|
+
* @returns Optimal threshold value
|
|
851
|
+
*/
|
|
852
|
+
declare function calibrateThreshold(knownMatches: Array<{
|
|
853
|
+
a: PhysicalDescriptor;
|
|
854
|
+
b: PhysicalDescriptor;
|
|
855
|
+
isMatch: boolean;
|
|
856
|
+
}>): number;
|
|
857
|
+
/**
|
|
858
|
+
* Evaluate consensus between two descriptors
|
|
859
|
+
*
|
|
860
|
+
* @param descriptorA - First physical descriptor
|
|
861
|
+
* @param descriptorB - Second physical descriptor
|
|
862
|
+
* @param config - Configuration options
|
|
863
|
+
* @returns Consensus evaluation result
|
|
864
|
+
*/
|
|
865
|
+
declare function evaluateConsensus(descriptorA: PhysicalDescriptor, descriptorB: PhysicalDescriptor, config?: ConsensusConfig): ConsensusResult;
|
|
866
|
+
|
|
867
|
+
/**
|
|
868
|
+
* M2M P2P Descriptor Exchange Protocol
|
|
869
|
+
*
|
|
870
|
+
* Protocol for exchanging descriptors between two devices without internet.
|
|
871
|
+
* Transport-agnostic (works over BLE, WiFi Direct, NFC, or TCP).
|
|
872
|
+
*/
|
|
873
|
+
|
|
874
|
+
interface P2PMessage {
|
|
875
|
+
type: 'handshake_init' | 'handshake_accept' | 'descriptor_exchange' | 'consensus_result' | 'error';
|
|
876
|
+
version: '1.0';
|
|
877
|
+
senderId: string;
|
|
878
|
+
recipientId?: string;
|
|
879
|
+
payload: unknown;
|
|
880
|
+
signature?: string;
|
|
881
|
+
timestamp: string;
|
|
882
|
+
nonce: string;
|
|
883
|
+
}
|
|
884
|
+
interface HandshakeInitPayload {
|
|
885
|
+
deviceId: string;
|
|
886
|
+
publicKey: string;
|
|
887
|
+
supportedAlgorithms: string[];
|
|
888
|
+
assetId: string;
|
|
889
|
+
}
|
|
890
|
+
interface HandshakeAcceptPayload {
|
|
891
|
+
deviceId: string;
|
|
892
|
+
publicKey: string;
|
|
893
|
+
selectedAlgorithm: string;
|
|
894
|
+
assetId: string;
|
|
895
|
+
}
|
|
896
|
+
interface DescriptorExchangePayload {
|
|
897
|
+
descriptor: PhysicalDescriptor;
|
|
898
|
+
assetId: string;
|
|
899
|
+
captureId: string;
|
|
900
|
+
}
|
|
901
|
+
interface ConsensusResultPayload {
|
|
902
|
+
consensusResult: ConsensusResult;
|
|
903
|
+
agreedByBoth: boolean;
|
|
904
|
+
}
|
|
905
|
+
interface ErrorPayload {
|
|
906
|
+
code: string;
|
|
907
|
+
message: string;
|
|
908
|
+
details?: Record<string, unknown>;
|
|
909
|
+
}
|
|
910
|
+
interface ValidationError {
|
|
911
|
+
field: string;
|
|
912
|
+
error: string;
|
|
913
|
+
}
|
|
914
|
+
interface ValidationResult$1 {
|
|
915
|
+
valid: boolean;
|
|
916
|
+
errors: ValidationError[];
|
|
917
|
+
}
|
|
918
|
+
/**
|
|
919
|
+
* Create a handshake initialization message
|
|
920
|
+
*/
|
|
921
|
+
declare function createHandshakeInit(deviceId: string, publicKey: string, assetId: string, supportedAlgorithms?: string[]): P2PMessage;
|
|
922
|
+
/**
|
|
923
|
+
* Create a handshake acceptance message
|
|
924
|
+
*/
|
|
925
|
+
declare function createHandshakeAccept(initMessage: P2PMessage, deviceId: string, publicKey: string, selectedAlgorithm?: string): P2PMessage;
|
|
926
|
+
/**
|
|
927
|
+
* Create a descriptor exchange message
|
|
928
|
+
*/
|
|
929
|
+
declare function createDescriptorExchange(deviceId: string, descriptor: PhysicalDescriptor, assetId: string, captureId?: string, recipientId?: string): P2PMessage;
|
|
930
|
+
/**
|
|
931
|
+
* Create a consensus result message
|
|
932
|
+
*/
|
|
933
|
+
declare function createConsensusResultMessage(deviceId: string, result: ConsensusResult, agreedByBoth?: boolean, recipientId?: string): P2PMessage;
|
|
934
|
+
/**
|
|
935
|
+
* Validate a P2P message
|
|
936
|
+
*/
|
|
937
|
+
declare function validateMessage(message: P2PMessage): ValidationResult$1;
|
|
938
|
+
/**
|
|
939
|
+
* Serialize a P2P message to JSON + base64
|
|
940
|
+
*/
|
|
941
|
+
declare function serializeMessage(message: P2PMessage): string;
|
|
942
|
+
/**
|
|
943
|
+
* Deserialize a P2P message from JSON + base64
|
|
944
|
+
*/
|
|
945
|
+
declare function deserializeMessage(data: string): P2PMessage;
|
|
946
|
+
|
|
947
|
+
interface M2MChallenge {
|
|
948
|
+
readonly id: string;
|
|
949
|
+
readonly assetId: string;
|
|
950
|
+
readonly nonce: string;
|
|
951
|
+
readonly algorithm: 'ed25519';
|
|
952
|
+
readonly expiresAt: string;
|
|
953
|
+
readonly createdAt: string;
|
|
954
|
+
}
|
|
955
|
+
interface M2MVerifyRequest {
|
|
956
|
+
readonly challengeId: string;
|
|
957
|
+
readonly response: string;
|
|
958
|
+
readonly deviceId?: string;
|
|
959
|
+
}
|
|
960
|
+
interface M2MVerifyResult {
|
|
961
|
+
readonly valid: boolean;
|
|
962
|
+
readonly assetId: string;
|
|
963
|
+
readonly challengeId: string;
|
|
964
|
+
readonly verifiedAt: string;
|
|
965
|
+
readonly deviceId?: string;
|
|
966
|
+
readonly reason?: 'expired' | 'bad_signature' | 'revoked';
|
|
967
|
+
}
|
|
968
|
+
interface M2MDevice {
|
|
969
|
+
readonly deviceId: string;
|
|
970
|
+
readonly label: string;
|
|
971
|
+
readonly publicKey: string;
|
|
972
|
+
readonly status: 'active' | 'revoked';
|
|
973
|
+
readonly lastSeenAt?: string;
|
|
974
|
+
readonly createdAt: string;
|
|
975
|
+
readonly metadata?: Record<string, unknown>;
|
|
976
|
+
}
|
|
977
|
+
interface InitiateChallengeParams {
|
|
978
|
+
readonly assetId: string;
|
|
979
|
+
readonly algorithm?: 'ed25519';
|
|
980
|
+
readonly ttlSeconds?: number;
|
|
981
|
+
}
|
|
982
|
+
interface RegisterDeviceParams {
|
|
983
|
+
readonly label: string;
|
|
984
|
+
readonly publicKey: string;
|
|
985
|
+
readonly metadata?: Record<string, unknown>;
|
|
986
|
+
}
|
|
987
|
+
/**
|
|
988
|
+
* Machine-to-Machine physical authentication protocol.
|
|
989
|
+
*
|
|
990
|
+
* Enables challenge-response verification between devices and assets.
|
|
991
|
+
*
|
|
992
|
+
* @remarks
|
|
993
|
+
* M2M endpoints are in preview and require enterprise access.
|
|
994
|
+
*
|
|
995
|
+
* @example
|
|
996
|
+
* ```typescript
|
|
997
|
+
* // 1. Initiate a challenge
|
|
998
|
+
* const challenge = await client.m2m.initiateChallenge({ assetId: 'ast_abc' });
|
|
999
|
+
*
|
|
1000
|
+
* // 2. Device signs the nonce (application-specific)
|
|
1001
|
+
* const responseSig = device.sign(challenge.nonce);
|
|
1002
|
+
*
|
|
1003
|
+
* // 3. Verify the response
|
|
1004
|
+
* const result = await client.m2m.verify({
|
|
1005
|
+
* challengeId: challenge.id,
|
|
1006
|
+
* response: responseSig,
|
|
1007
|
+
* });
|
|
1008
|
+
* console.log(result.valid); // true or false
|
|
1009
|
+
* ```
|
|
1010
|
+
*/
|
|
1011
|
+
declare class M2MResource {
|
|
1012
|
+
private readonly request;
|
|
1013
|
+
constructor(request: RequestFn);
|
|
1014
|
+
/**
|
|
1015
|
+
* Initiate an M2M challenge for an asset.
|
|
1016
|
+
*/
|
|
1017
|
+
initiateChallenge(params: InitiateChallengeParams): Promise<M2MChallenge>;
|
|
1018
|
+
/**
|
|
1019
|
+
* Verify an M2M challenge response.
|
|
1020
|
+
*/
|
|
1021
|
+
verify(params: M2MVerifyRequest): Promise<M2MVerifyResult>;
|
|
1022
|
+
/**
|
|
1023
|
+
* Register a verifier device.
|
|
1024
|
+
*/
|
|
1025
|
+
registerDevice(params: RegisterDeviceParams): Promise<M2MDevice>;
|
|
1026
|
+
/**
|
|
1027
|
+
* Get a verifier device by ID.
|
|
1028
|
+
*/
|
|
1029
|
+
getDevice(deviceId: string): Promise<M2MDevice>;
|
|
1030
|
+
/**
|
|
1031
|
+
* List all registered verifier devices.
|
|
1032
|
+
*/
|
|
1033
|
+
listDevices(): Promise<M2MDevice[]>;
|
|
1034
|
+
/**
|
|
1035
|
+
* Revoke a verifier device.
|
|
1036
|
+
*/
|
|
1037
|
+
revokeDevice(deviceId: string): Promise<void>;
|
|
1038
|
+
/**
|
|
1039
|
+
* Evaluate consensus between two physical descriptors (local operation, no API call)
|
|
1040
|
+
*/
|
|
1041
|
+
consensus(descriptorA: PhysicalDescriptor, descriptorB: PhysicalDescriptor, config?: ConsensusConfig): ConsensusResult;
|
|
1042
|
+
/**
|
|
1043
|
+
* Create a new local audit trail (no API call)
|
|
1044
|
+
*/
|
|
1045
|
+
createAuditTrail(chainId?: string): AuditChain;
|
|
1046
|
+
/**
|
|
1047
|
+
* Verify audit trail integrity (local operation, no API call)
|
|
1048
|
+
*/
|
|
1049
|
+
verifyAuditTrail(chain: AuditChain): Promise<{
|
|
1050
|
+
valid: boolean;
|
|
1051
|
+
brokenAt?: number;
|
|
1052
|
+
error?: string;
|
|
1053
|
+
}>;
|
|
1054
|
+
}
|
|
1055
|
+
|
|
506
1056
|
/**
|
|
507
1057
|
* Provenance Resource
|
|
508
1058
|
*
|
|
@@ -711,6 +1261,41 @@ declare class SchemasResource {
|
|
|
711
1261
|
private stripUndefined;
|
|
712
1262
|
}
|
|
713
1263
|
|
|
1264
|
+
/**
|
|
1265
|
+
* Tenants Resource
|
|
1266
|
+
*
|
|
1267
|
+
* Tenant management and quota operations.
|
|
1268
|
+
*/
|
|
1269
|
+
|
|
1270
|
+
interface GetUsageParams {
|
|
1271
|
+
readonly period?: 'day' | 'week' | 'month' | 'billing_cycle';
|
|
1272
|
+
}
|
|
1273
|
+
interface GetUsageBreakdownParams {
|
|
1274
|
+
readonly period?: string;
|
|
1275
|
+
readonly groupBy?: 'endpoint' | 'key' | 'resource';
|
|
1276
|
+
}
|
|
1277
|
+
declare class TenantsResource {
|
|
1278
|
+
private readonly request;
|
|
1279
|
+
constructor(request: RequestFn);
|
|
1280
|
+
/**
|
|
1281
|
+
* Get information about the current tenant.
|
|
1282
|
+
*/
|
|
1283
|
+
getCurrent(): Promise<Tenant>;
|
|
1284
|
+
/**
|
|
1285
|
+
* Get resource limits for the current tenant based on their plan.
|
|
1286
|
+
*/
|
|
1287
|
+
getLimits(): Promise<TenantLimits>;
|
|
1288
|
+
/**
|
|
1289
|
+
* Get usage metrics for a specified period.
|
|
1290
|
+
*/
|
|
1291
|
+
getUsage(params?: GetUsageParams): Promise<UsageReport>;
|
|
1292
|
+
/**
|
|
1293
|
+
* Get usage metrics broken down by endpoint, key, or resource.
|
|
1294
|
+
*/
|
|
1295
|
+
getUsageBreakdown(params?: GetUsageBreakdownParams): Promise<EndpointUsage[]>;
|
|
1296
|
+
private buildQuery;
|
|
1297
|
+
}
|
|
1298
|
+
|
|
714
1299
|
/**
|
|
715
1300
|
* optropic - OptropicClient
|
|
716
1301
|
*
|
|
@@ -758,14 +1343,18 @@ declare class OptropicClient {
|
|
|
758
1343
|
private readonly retryConfig;
|
|
759
1344
|
private readonly _sandbox;
|
|
760
1345
|
private readonly _debug;
|
|
1346
|
+
private _rateLimit;
|
|
761
1347
|
readonly assets: AssetsResource;
|
|
762
1348
|
readonly audit: AuditResource;
|
|
1349
|
+
readonly batches: BatchesResource;
|
|
763
1350
|
readonly compliance: ComplianceResource;
|
|
764
1351
|
readonly documents: DocumentsResource;
|
|
765
1352
|
readonly keys: KeysResource;
|
|
766
1353
|
readonly keysets: KeysetsResource;
|
|
1354
|
+
readonly m2m: M2MResource;
|
|
767
1355
|
readonly provenance: ProvenanceResource;
|
|
768
1356
|
readonly schemas: SchemasResource;
|
|
1357
|
+
readonly tenants: TenantsResource;
|
|
769
1358
|
constructor(config: OptropicConfig);
|
|
770
1359
|
/** True when the client is in sandbox mode (test API key or explicit override). */
|
|
771
1360
|
get isSandbox(): boolean;
|
|
@@ -773,6 +1362,13 @@ declare class OptropicClient {
|
|
|
773
1362
|
get isLive(): boolean;
|
|
774
1363
|
/** Returns 'sandbox' or 'live'. */
|
|
775
1364
|
get environment(): 'sandbox' | 'live';
|
|
1365
|
+
/** Last known rate limit status, updated after every API call. Returns null until the first request. */
|
|
1366
|
+
get rateLimit(): RateLimitInfo | null;
|
|
1367
|
+
/**
|
|
1368
|
+
* Get quota information for the current API key.
|
|
1369
|
+
* Based on the last known rate limit from previous API calls.
|
|
1370
|
+
*/
|
|
1371
|
+
getQuota(): QuotaInfo;
|
|
776
1372
|
private redact;
|
|
777
1373
|
private logRequest;
|
|
778
1374
|
private logResponse;
|
|
@@ -938,6 +1534,12 @@ interface ConformityDeclaration {
|
|
|
938
1534
|
readonly issuedBy?: string;
|
|
939
1535
|
readonly validUntil?: string;
|
|
940
1536
|
}
|
|
1537
|
+
interface HazardousSubstanceEntry {
|
|
1538
|
+
readonly name: string;
|
|
1539
|
+
readonly casNumber?: string;
|
|
1540
|
+
readonly concentration?: number;
|
|
1541
|
+
readonly unit?: string;
|
|
1542
|
+
}
|
|
941
1543
|
interface BatteryPassportData {
|
|
942
1544
|
readonly type: 'battery';
|
|
943
1545
|
/** Battery chemistry (e.g., "NMC", "LFP", "NCA"). */
|
|
@@ -954,10 +1556,64 @@ interface BatteryPassportData {
|
|
|
954
1556
|
readonly lithiumContent?: number;
|
|
955
1557
|
/** Recycled cobalt percentage. */
|
|
956
1558
|
readonly recycledCobaltPercent?: number;
|
|
1559
|
+
/** Recycled lithium percentage. */
|
|
1560
|
+
readonly recycledLithiumPercent?: number;
|
|
1561
|
+
/** Recycled nickel percentage. */
|
|
1562
|
+
readonly recycledNickelPercent?: number;
|
|
1563
|
+
/** Recycled lead percentage. */
|
|
1564
|
+
readonly recycledLeadPercent?: number;
|
|
957
1565
|
/** Carbon footprint class (A-G). */
|
|
958
1566
|
readonly carbonClass?: string;
|
|
959
1567
|
/** Expected lifetime in charge cycles. */
|
|
960
1568
|
readonly expectedLifetimeCycles?: number;
|
|
1569
|
+
/** URL to supply chain due diligence report. */
|
|
1570
|
+
readonly dueDiligenceUrl?: string;
|
|
1571
|
+
/** EU economic operator ID (mandatory Annex XIII). */
|
|
1572
|
+
readonly manufacturerIdentification: string;
|
|
1573
|
+
/** Manufacturing date in ISO 8601 format (mandatory Annex XIII). */
|
|
1574
|
+
readonly manufacturingDate: string;
|
|
1575
|
+
/** Facility location where battery was manufactured (mandatory Annex XIII). */
|
|
1576
|
+
readonly manufacturingPlace: string;
|
|
1577
|
+
/** Battery weight in kilograms (mandatory Annex XIII). */
|
|
1578
|
+
readonly batteryWeight: number;
|
|
1579
|
+
/** Battery status/lifecycle stage (mandatory Annex XIII). */
|
|
1580
|
+
readonly batteryStatus: 'original' | 'repurposed' | 'remanufactured' | 'waste';
|
|
1581
|
+
/** Rated capacity in Amp-hours (mandatory Annex XIII). */
|
|
1582
|
+
readonly ratedCapacityAh: number;
|
|
1583
|
+
/** Minimum voltage in Volts (mandatory Annex XIII). */
|
|
1584
|
+
readonly voltageMinV: number;
|
|
1585
|
+
/** Maximum voltage in Volts (mandatory Annex XIII). */
|
|
1586
|
+
readonly voltageMaxV: number;
|
|
1587
|
+
/** Nominal voltage in Volts (mandatory Annex XIII). */
|
|
1588
|
+
readonly voltageNominalV: number;
|
|
1589
|
+
/** Minimum operating temperature in Celsius (mandatory Annex XIII). */
|
|
1590
|
+
readonly temperatureRangeMinC: number;
|
|
1591
|
+
/** Maximum operating temperature in Celsius (mandatory Annex XIII). */
|
|
1592
|
+
readonly temperatureRangeMaxC: number;
|
|
1593
|
+
/** Original power capability in Watts (mandatory Annex XIII). */
|
|
1594
|
+
readonly originalPowerCapabilityW: number;
|
|
1595
|
+
/** Round-trip efficiency as percentage 0-100 (mandatory Annex XIII). */
|
|
1596
|
+
readonly roundTripEfficiency: number;
|
|
1597
|
+
/** Internal resistance in Ohms (mandatory Annex XIII). */
|
|
1598
|
+
readonly internalResistanceOhm: number;
|
|
1599
|
+
/** Detailed cell chemistry information (mandatory Annex XIII). */
|
|
1600
|
+
readonly cellChemistryDetail: string;
|
|
1601
|
+
/** List of hazardous substances contained in the battery (mandatory Annex XIII). */
|
|
1602
|
+
readonly hazardousSubstances: HazardousSubstanceEntry[];
|
|
1603
|
+
/** Carbon footprint value in kg CO2e per kWh (mandatory Annex XIII). */
|
|
1604
|
+
readonly carbonFootprintPerKwh: number;
|
|
1605
|
+
/** URL to carbon footprint study/report (mandatory Annex XIII). */
|
|
1606
|
+
readonly carbonFootprintStudyUrl: string;
|
|
1607
|
+
/** URL to supply chain due diligence policy (mandatory Annex XIII). */
|
|
1608
|
+
readonly supplyChainDueDiligencePolicy: string;
|
|
1609
|
+
/** Third-party verifier ID (e.g., notified body number) (mandatory Annex XIII). */
|
|
1610
|
+
readonly thirdPartyVerifierId: string;
|
|
1611
|
+
/** URL to battery dismantling/disassembly instructions (mandatory Annex XIII). */
|
|
1612
|
+
readonly dismantlingInstructions: string;
|
|
1613
|
+
/** URL to battery safety instructions/warnings (mandatory Annex XIII). */
|
|
1614
|
+
readonly safetyInstructions: string;
|
|
1615
|
+
/** Type of extinguishing agent suitable for battery fires (mandatory Annex XIII). */
|
|
1616
|
+
readonly extinguishingAgent: string;
|
|
961
1617
|
}
|
|
962
1618
|
interface TextilePassportData {
|
|
963
1619
|
readonly type: 'textile';
|
|
@@ -1011,21 +1667,489 @@ declare function validateDPPMetadata(metadata: DPPMetadata): {
|
|
|
1011
1667
|
valid: boolean;
|
|
1012
1668
|
errors: string[];
|
|
1013
1669
|
};
|
|
1014
|
-
|
|
1015
1670
|
/**
|
|
1016
|
-
*
|
|
1017
|
-
*
|
|
1018
|
-
* Verifies that incoming webhook payloads were signed by Optropic.
|
|
1019
|
-
* Uses the endpoint secret provided when the webhook was registered.
|
|
1671
|
+
* Validate a battery passport against Annex XIII requirements.
|
|
1672
|
+
* Returns validation result with all errors and warnings.
|
|
1020
1673
|
*
|
|
1021
|
-
* @
|
|
1674
|
+
* @example
|
|
1675
|
+
* ```typescript
|
|
1676
|
+
* const result = validateBatteryPassport(batteryData);
|
|
1677
|
+
* if (!result.valid) {
|
|
1678
|
+
* console.error('Validation errors:', result.errors);
|
|
1679
|
+
* console.warn('Warnings:', result.warnings);
|
|
1680
|
+
* }
|
|
1681
|
+
* ```
|
|
1022
1682
|
*/
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1683
|
+
declare function validateBatteryPassport(data: BatteryPassportData): {
|
|
1684
|
+
valid: boolean;
|
|
1685
|
+
errors: string[];
|
|
1686
|
+
warnings: string[];
|
|
1687
|
+
};
|
|
1688
|
+
/**
|
|
1689
|
+
* Build a GS1 Digital Link URI for a battery passport.
|
|
1690
|
+
* Creates a URL containing the battery's GTIN and serial number for QR encoding.
|
|
1691
|
+
*
|
|
1692
|
+
* @example
|
|
1693
|
+
* ```typescript
|
|
1694
|
+
* const uri = buildBatteryPassportQR({
|
|
1695
|
+
* productId: '04012345000010',
|
|
1696
|
+
* sectorData: { type: 'battery', ... }
|
|
1697
|
+
* });
|
|
1698
|
+
* // Returns: 'https://id.gs1.org/01/04012345000010/21/SN123'
|
|
1699
|
+
* ```
|
|
1700
|
+
*/
|
|
1701
|
+
declare function buildBatteryPassportQR(metadata: DPPMetadata): string;
|
|
1702
|
+
|
|
1703
|
+
/**
|
|
1704
|
+
* GS1 Digital Link URI Parser & Resolver
|
|
1705
|
+
*
|
|
1706
|
+
* Supports parsing and building GS1 Digital Link URIs according to the
|
|
1707
|
+
* GS1 Digital Link specification, with validation of GTIN check digits
|
|
1708
|
+
* and mapping to Optropic asset lookups.
|
|
1709
|
+
*
|
|
1710
|
+
* @module optropic/gs1-resolver
|
|
1711
|
+
*/
|
|
1712
|
+
/**
|
|
1713
|
+
* Supported GS1 Application Identifiers (AI).
|
|
1714
|
+
* Maps AI numeric codes to human-readable names.
|
|
1715
|
+
*/
|
|
1716
|
+
type GS1ApplicationIdentifier = '01' | '21' | '10' | '11' | '17' | '3103' | '3922' | '8200' | '254' | '414';
|
|
1717
|
+
/**
|
|
1718
|
+
* Parsed GS1 Digital Link URI component.
|
|
1719
|
+
*/
|
|
1720
|
+
interface GS1ParsedComponent {
|
|
1721
|
+
readonly ai: GS1ApplicationIdentifier;
|
|
1722
|
+
readonly value: string;
|
|
1723
|
+
readonly label: string;
|
|
1724
|
+
}
|
|
1725
|
+
/**
|
|
1726
|
+
* Fully parsed GS1 Digital Link URI.
|
|
1727
|
+
*/
|
|
1728
|
+
interface GS1ParsedURI {
|
|
1729
|
+
readonly domain: string;
|
|
1730
|
+
readonly gtin?: string;
|
|
1731
|
+
readonly serialNumber?: string;
|
|
1732
|
+
readonly batchLot?: string;
|
|
1733
|
+
readonly productionDate?: string;
|
|
1734
|
+
readonly expiryDate?: string;
|
|
1735
|
+
readonly netWeightKg?: number;
|
|
1736
|
+
readonly price?: string;
|
|
1737
|
+
readonly url?: string;
|
|
1738
|
+
readonly gln?: string;
|
|
1739
|
+
readonly extension?: string;
|
|
1740
|
+
readonly allComponents: GS1ParsedComponent[];
|
|
1741
|
+
readonly queryParams?: Record<string, string>;
|
|
1742
|
+
}
|
|
1743
|
+
/**
|
|
1744
|
+
* GS1 Digital Link URI builder input.
|
|
1745
|
+
*/
|
|
1746
|
+
interface GS1BuilderInput {
|
|
1747
|
+
readonly domain?: string;
|
|
1748
|
+
readonly gtin: string;
|
|
1749
|
+
readonly serialNumber?: string;
|
|
1750
|
+
readonly batchLot?: string;
|
|
1751
|
+
readonly productionDate?: string;
|
|
1752
|
+
readonly expiryDate?: string;
|
|
1753
|
+
readonly netWeightKg?: number;
|
|
1754
|
+
readonly price?: string;
|
|
1755
|
+
readonly url?: string;
|
|
1756
|
+
readonly gln?: string;
|
|
1757
|
+
readonly extension?: string;
|
|
1758
|
+
readonly queryParams?: Record<string, string>;
|
|
1759
|
+
}
|
|
1760
|
+
/**
|
|
1761
|
+
* GTIN validation result.
|
|
1762
|
+
*/
|
|
1763
|
+
interface GTINValidationResult {
|
|
1764
|
+
readonly valid: boolean;
|
|
1765
|
+
readonly checkDigit: number;
|
|
1766
|
+
readonly message: string;
|
|
1767
|
+
}
|
|
1768
|
+
/**
|
|
1769
|
+
* GS1 Digital Link to Optropic mapping.
|
|
1770
|
+
*/
|
|
1771
|
+
interface OptropicAssetLookup {
|
|
1772
|
+
readonly productId: string;
|
|
1773
|
+
readonly serialNumber?: string;
|
|
1774
|
+
readonly batchId?: string;
|
|
1775
|
+
readonly lookupQuery: string;
|
|
1776
|
+
}
|
|
1777
|
+
/**
|
|
1778
|
+
* QR code data payload configuration.
|
|
1779
|
+
*/
|
|
1780
|
+
interface QRCodePayload {
|
|
1781
|
+
readonly type: 'gs1-digital-link' | 'url' | 'ean13';
|
|
1782
|
+
readonly data: string;
|
|
1783
|
+
readonly encodingMode: 'url' | 'raw';
|
|
1784
|
+
}
|
|
1785
|
+
/**
|
|
1786
|
+
* Validate GTIN check digit using mod-10 algorithm.
|
|
1787
|
+
* Works for GTIN-8, GTIN-12, GTIN-13, and GTIN-14.
|
|
1788
|
+
*
|
|
1789
|
+
* @example
|
|
1790
|
+
* ```typescript
|
|
1791
|
+
* const result = validateGTIN('04012345000010');
|
|
1792
|
+
* console.log(result.valid); // true if check digit is correct
|
|
1793
|
+
* ```
|
|
1794
|
+
*/
|
|
1795
|
+
declare function validateGTIN(gtin: string): GTINValidationResult;
|
|
1796
|
+
/**
|
|
1797
|
+
* Parse a GS1 Digital Link URI into structured components.
|
|
1798
|
+
*
|
|
1799
|
+
* @example
|
|
1800
|
+
* ```typescript
|
|
1801
|
+
* const parsed = parseGS1DigitalLink(
|
|
1802
|
+
* 'https://id.gs1.org/01/04012345000010/21/SN001'
|
|
1803
|
+
* );
|
|
1804
|
+
* console.log(parsed.gtin); // '04012345000010'
|
|
1805
|
+
* console.log(parsed.serialNumber); // 'SN001'
|
|
1806
|
+
* ```
|
|
1807
|
+
*/
|
|
1808
|
+
declare function parseGS1DigitalLink(uri: string): GS1ParsedURI;
|
|
1809
|
+
/**
|
|
1810
|
+
* Build a GS1 Digital Link URI from components.
|
|
1811
|
+
*
|
|
1812
|
+
* @example
|
|
1813
|
+
* ```typescript
|
|
1814
|
+
* const uri = buildGS1DigitalLink({
|
|
1815
|
+
* gtin: '04012345000010',
|
|
1816
|
+
* serialNumber: 'SN001',
|
|
1817
|
+
* domain: 'https://id.optropic.com',
|
|
1818
|
+
* });
|
|
1819
|
+
* // Returns: 'https://id.optropic.com/01/04012345000010/21/SN001'
|
|
1820
|
+
* ```
|
|
1821
|
+
*/
|
|
1822
|
+
declare function buildGS1DigitalLink(input: GS1BuilderInput): string;
|
|
1823
|
+
/**
|
|
1824
|
+
* Map a parsed GS1 Digital Link to an Optropic asset lookup query.
|
|
1825
|
+
*
|
|
1826
|
+
* @example
|
|
1827
|
+
* ```typescript
|
|
1828
|
+
* const parsed = parseGS1DigitalLink('https://id.gs1.org/01/04012345000010/21/SN001');
|
|
1829
|
+
* const lookup = mapToOptropicAsset(parsed);
|
|
1830
|
+
* // Returns: { productId: '04012345000010', serialNumber: 'SN001', ... }
|
|
1831
|
+
* ```
|
|
1832
|
+
*/
|
|
1833
|
+
declare function mapToOptropicAsset(parsed: GS1ParsedURI): OptropicAssetLookup;
|
|
1834
|
+
/**
|
|
1835
|
+
* Generate a QR code payload suitable for GS1 Digital Link encoding.
|
|
1836
|
+
*
|
|
1837
|
+
* @example
|
|
1838
|
+
* ```typescript
|
|
1839
|
+
* const payload = generateQRCodePayload({
|
|
1840
|
+
* gtin: '04012345000010',
|
|
1841
|
+
* serialNumber: 'SN001',
|
|
1842
|
+
* });
|
|
1843
|
+
* // Returns: { type: 'gs1-digital-link', data: 'https://id.gs1.org/01/...', ... }
|
|
1844
|
+
* ```
|
|
1845
|
+
*/
|
|
1846
|
+
declare function generateQRCodePayload(input: GS1BuilderInput): QRCodePayload;
|
|
1847
|
+
/**
|
|
1848
|
+
* Check if a value is a valid GS1 Application Identifier.
|
|
1849
|
+
*/
|
|
1850
|
+
declare function isValidAI(ai: string): ai is GS1ApplicationIdentifier;
|
|
1851
|
+
/**
|
|
1852
|
+
* Get human-readable label for a GS1 Application Identifier.
|
|
1853
|
+
*/
|
|
1854
|
+
declare function getAILabel(ai: GS1ApplicationIdentifier): string;
|
|
1855
|
+
/**
|
|
1856
|
+
* Get all supported GS1 Application Identifiers.
|
|
1857
|
+
*/
|
|
1858
|
+
declare function getSupportedAIs(): GS1ApplicationIdentifier[];
|
|
1859
|
+
|
|
1860
|
+
/**
|
|
1861
|
+
* DPP Access Control Levels
|
|
1862
|
+
*
|
|
1863
|
+
* Implements tiered access control for EU Digital Product Passport data.
|
|
1864
|
+
* Required before the EU DPP Registry launch (19 July 2026).
|
|
1865
|
+
*
|
|
1866
|
+
* The ESPR regulation mandates that DPP data is available at different
|
|
1867
|
+
* levels depending on the requester's role:
|
|
1868
|
+
*
|
|
1869
|
+
* - **public**: Consumer-facing data (product name, manufacturer,
|
|
1870
|
+
* carbon footprint, recycled content, repairability score).
|
|
1871
|
+
* - **authenticated**: Data available to verified supply chain partners
|
|
1872
|
+
* (substances of concern, sector-specific data, conformity declarations).
|
|
1873
|
+
* - **regulatory**: Full dataset available to market surveillance
|
|
1874
|
+
* authorities (all fields + audit trail).
|
|
1875
|
+
* - **owner**: Complete data including internal metadata, accessible
|
|
1876
|
+
* only to the economic operator who created the passport.
|
|
1877
|
+
*
|
|
1878
|
+
* @module optropic/dpp-access
|
|
1879
|
+
*/
|
|
1880
|
+
|
|
1881
|
+
/**
|
|
1882
|
+
* DPP access levels, ordered from least to most privileged.
|
|
1883
|
+
*/
|
|
1884
|
+
declare const DPPAccessLevel: {
|
|
1885
|
+
/** Consumer-facing public data. */
|
|
1886
|
+
readonly PUBLIC: "public";
|
|
1887
|
+
/** Verified supply chain partner. */
|
|
1888
|
+
readonly AUTHENTICATED: "authenticated";
|
|
1889
|
+
/** Market surveillance authority. */
|
|
1890
|
+
readonly REGULATORY: "regulatory";
|
|
1891
|
+
/** Economic operator (data owner). */
|
|
1892
|
+
readonly OWNER: "owner";
|
|
1893
|
+
/**
|
|
1894
|
+
* Check if a level has at least the privilege of another.
|
|
1895
|
+
* Useful for authorization checks.
|
|
1896
|
+
*
|
|
1897
|
+
* @example
|
|
1898
|
+
* ```typescript
|
|
1899
|
+
* DPPAccessLevel.isAtLeast('regulatory', 'authenticated'); // true
|
|
1900
|
+
* DPPAccessLevel.isAtLeast('public', 'regulatory'); // false
|
|
1901
|
+
* ```
|
|
1902
|
+
*/
|
|
1903
|
+
readonly isAtLeast: (level: DPPAccessLevelValue, required: DPPAccessLevelValue) => boolean;
|
|
1904
|
+
};
|
|
1905
|
+
type DPPAccessLevelValue = 'public' | 'authenticated' | 'regulatory' | 'owner';
|
|
1906
|
+
/**
|
|
1907
|
+
* Defines which DPP fields are visible at each access level.
|
|
1908
|
+
*/
|
|
1909
|
+
interface DPPFieldVisibility {
|
|
1910
|
+
/** Field name (matches DPPMetadata property). */
|
|
1911
|
+
readonly field: string;
|
|
1912
|
+
/** Minimum access level required to view this field. */
|
|
1913
|
+
readonly minLevel: DPPAccessLevelValue;
|
|
1914
|
+
/** Optional: override per DPP category. */
|
|
1915
|
+
readonly categoryOverride?: Partial<Record<DPPCategory, DPPAccessLevelValue>>;
|
|
1916
|
+
}
|
|
1917
|
+
/**
|
|
1918
|
+
* Complete access policy for a DPP dataset.
|
|
1919
|
+
*/
|
|
1920
|
+
interface DPPAccessPolicy {
|
|
1921
|
+
/** Default access level applied when none is specified. */
|
|
1922
|
+
readonly defaultLevel: DPPAccessLevelValue;
|
|
1923
|
+
/** Per-field visibility rules. */
|
|
1924
|
+
readonly fields: DPPFieldVisibility[];
|
|
1925
|
+
/** Whether redacted fields show "[REDACTED]" or are omitted entirely. */
|
|
1926
|
+
readonly redactionMode: 'omit' | 'placeholder';
|
|
1927
|
+
}
|
|
1928
|
+
/**
|
|
1929
|
+
* Context for an access control decision.
|
|
1930
|
+
*/
|
|
1931
|
+
interface DPPAccessContext {
|
|
1932
|
+
/** The requester's access level. */
|
|
1933
|
+
readonly level: DPPAccessLevelValue;
|
|
1934
|
+
/** Optional: the specific DPP category (for category-specific overrides). */
|
|
1935
|
+
readonly category?: DPPCategory;
|
|
1936
|
+
/** Optional: if true, include redaction markers instead of omitting fields. */
|
|
1937
|
+
readonly showRedacted?: boolean;
|
|
1938
|
+
}
|
|
1939
|
+
/**
|
|
1940
|
+
* Get the default DPP access policy.
|
|
1941
|
+
*
|
|
1942
|
+
* Returns the policy that aligns with ESPR and EU Battery Regulation
|
|
1943
|
+
* requirements. Can be customized per tenant via the API's compliance
|
|
1944
|
+
* configuration.
|
|
1945
|
+
*
|
|
1946
|
+
* @param overrides - Optional field visibility overrides.
|
|
1947
|
+
* @returns The access policy.
|
|
1948
|
+
*/
|
|
1949
|
+
declare function getDPPAccessPolicy(overrides?: DPPFieldVisibility[]): DPPAccessPolicy;
|
|
1950
|
+
/**
|
|
1951
|
+
* Filter DPP metadata based on the requester's access level.
|
|
1952
|
+
*
|
|
1953
|
+
* Returns a new object containing only the fields the requester
|
|
1954
|
+
* is authorized to see. Fields below the access threshold are
|
|
1955
|
+
* either omitted or replaced with "[REDACTED]" placeholders.
|
|
1956
|
+
*
|
|
1957
|
+
* @param metadata - Full DPP metadata object (all fields).
|
|
1958
|
+
* @param context - Access context (level, category, redaction preference).
|
|
1959
|
+
* @param policy - Optional custom access policy; uses default if omitted.
|
|
1960
|
+
* @returns Filtered metadata object.
|
|
1961
|
+
*
|
|
1962
|
+
* @example
|
|
1963
|
+
* ```typescript
|
|
1964
|
+
* import { filterDPPByAccess, DPPAccessLevel } from 'optropic';
|
|
1965
|
+
*
|
|
1966
|
+
* // Consumer view — only public fields
|
|
1967
|
+
* const publicView = filterDPPByAccess(fullMetadata, {
|
|
1968
|
+
* level: DPPAccessLevel.PUBLIC,
|
|
1969
|
+
* category: 'battery',
|
|
1970
|
+
* });
|
|
1971
|
+
*
|
|
1972
|
+
* // Regulatory view — full access
|
|
1973
|
+
* const regulatoryView = filterDPPByAccess(fullMetadata, {
|
|
1974
|
+
* level: DPPAccessLevel.REGULATORY,
|
|
1975
|
+
* category: 'battery',
|
|
1976
|
+
* showRedacted: true,
|
|
1977
|
+
* });
|
|
1978
|
+
* ```
|
|
1979
|
+
*/
|
|
1980
|
+
declare function filterDPPByAccess(metadata: Record<string, unknown>, context: DPPAccessContext, policy?: DPPAccessPolicy): Record<string, unknown>;
|
|
1981
|
+
|
|
1982
|
+
/**
|
|
1983
|
+
* EPCIS 2.0 Event Type Mapping
|
|
1984
|
+
*
|
|
1985
|
+
* Maps Optropic provenance events to GS1 EPCIS 2.0 event types and
|
|
1986
|
+
* vocabularies. Enables interoperability with supply chain systems that
|
|
1987
|
+
* speak EPCIS (SAP, Oracle, TraceLink, etc.) and aligns with
|
|
1988
|
+
* DIN SPEC 91406 product identification.
|
|
1989
|
+
*
|
|
1990
|
+
* EPCIS 2.0 spec: GS1 General Specification §7 + EPCIS/CBV 2.0
|
|
1991
|
+
* @see https://www.gs1.org/standards/epcis
|
|
1992
|
+
*
|
|
1993
|
+
* @module optropic/epcis
|
|
1994
|
+
*/
|
|
1995
|
+
|
|
1996
|
+
/**
|
|
1997
|
+
* GS1 EPCIS 2.0 top-level event types.
|
|
1998
|
+
*
|
|
1999
|
+
* - ObjectEvent: observation of one or more objects
|
|
2000
|
+
* - AggregationEvent: parent-child containment (packing, unpacking)
|
|
2001
|
+
* - TransactionEvent: link to business transaction
|
|
2002
|
+
* - TransformationEvent: input→output manufacturing step
|
|
2003
|
+
* - AssociationEvent: non-containment relationship (sensor association)
|
|
2004
|
+
*/
|
|
2005
|
+
type EPCISEventType = 'ObjectEvent' | 'AggregationEvent' | 'TransactionEvent' | 'TransformationEvent' | 'AssociationEvent';
|
|
2006
|
+
/**
|
|
2007
|
+
* GS1 Core Business Vocabulary (CBV) 2.0 — Business Step values.
|
|
2008
|
+
* Subset most relevant for DPP / provenance chains.
|
|
2009
|
+
*/
|
|
2010
|
+
type EPCISBizStep = 'urn:epcglobal:cbv:bizstep:commissioning' | 'urn:epcglobal:cbv:bizstep:shipping' | 'urn:epcglobal:cbv:bizstep:receiving' | 'urn:epcglobal:cbv:bizstep:inspecting' | 'urn:epcglobal:cbv:bizstep:destroying' | 'urn:epcglobal:cbv:bizstep:encoding' | 'urn:epcglobal:cbv:bizstep:packing' | 'urn:epcglobal:cbv:bizstep:unpacking' | 'urn:epcglobal:cbv:bizstep:transforming' | 'urn:epcglobal:cbv:bizstep:holding' | 'urn:epcglobal:cbv:bizstep:transporting' | 'urn:epcglobal:cbv:bizstep:repairing' | 'urn:epcglobal:cbv:bizstep:cycle_counting' | 'urn:epcglobal:cbv:bizstep:decommissioning' | 'urn:epcglobal:cbv:bizstep:retail_selling' | 'urn:epcglobal:cbv:bizstep:void_shipping' | string;
|
|
2011
|
+
/**
|
|
2012
|
+
* GS1 CBV 2.0 — Disposition values.
|
|
2013
|
+
*/
|
|
2014
|
+
type EPCISDisposition = 'urn:epcglobal:cbv:disp:active' | 'urn:epcglobal:cbv:disp:in_transit' | 'urn:epcglobal:cbv:disp:recalled' | 'urn:epcglobal:cbv:disp:destroyed' | 'urn:epcglobal:cbv:disp:in_progress' | 'urn:epcglobal:cbv:disp:encoded' | 'urn:epcglobal:cbv:disp:inactive' | 'urn:epcglobal:cbv:disp:needs_replacement' | 'urn:epcglobal:cbv:disp:returned' | string;
|
|
2015
|
+
/**
|
|
2016
|
+
* Result of mapping an Optropic provenance event to EPCIS 2.0.
|
|
2017
|
+
*/
|
|
2018
|
+
interface EPCISMapping {
|
|
2019
|
+
/** The EPCIS event type. */
|
|
2020
|
+
readonly eventType: EPCISEventType;
|
|
2021
|
+
/** CBV business step URN. */
|
|
2022
|
+
readonly bizStep: EPCISBizStep;
|
|
2023
|
+
/** CBV disposition URN (state of the object after the event). */
|
|
2024
|
+
readonly disposition: EPCISDisposition;
|
|
2025
|
+
/** Whether this is a one-to-one mapping (true) or a best-effort approximation. */
|
|
2026
|
+
readonly exact: boolean;
|
|
2027
|
+
/** Human-readable description of the mapping rationale. */
|
|
2028
|
+
readonly note: string;
|
|
2029
|
+
}
|
|
2030
|
+
/**
|
|
2031
|
+
* Full EPCIS 2.0 event document, ready for JSON-LD serialization.
|
|
2032
|
+
* Conforms to the EPCIS 2.0 JSON/JSON-LD binding.
|
|
2033
|
+
*/
|
|
2034
|
+
interface EPCISEventDocument {
|
|
2035
|
+
/** JSON-LD context. */
|
|
2036
|
+
readonly '@context': (string | Record<string, string>)[];
|
|
2037
|
+
/** EPCIS document type. */
|
|
2038
|
+
readonly type: 'EPCISDocument';
|
|
2039
|
+
/** Schema version. */
|
|
2040
|
+
readonly schemaVersion: '2.0';
|
|
2041
|
+
/** Creation date. */
|
|
2042
|
+
readonly creationDate: string;
|
|
2043
|
+
/** The EPCIS event body. */
|
|
2044
|
+
readonly epcisBody: {
|
|
2045
|
+
readonly eventList: EPCISEvent[];
|
|
2046
|
+
};
|
|
2047
|
+
}
|
|
2048
|
+
/**
|
|
2049
|
+
* A single EPCIS 2.0 event in the JSON-LD representation.
|
|
2050
|
+
*/
|
|
2051
|
+
interface EPCISEvent {
|
|
2052
|
+
readonly type: EPCISEventType;
|
|
2053
|
+
readonly eventTime: string;
|
|
2054
|
+
readonly eventTimeZoneOffset: string;
|
|
2055
|
+
readonly bizStep: EPCISBizStep;
|
|
2056
|
+
readonly disposition: EPCISDisposition;
|
|
2057
|
+
/** EPC list (mapped from Optropic asset IDs). */
|
|
2058
|
+
readonly epcList?: string[];
|
|
2059
|
+
/** Read point (location where event occurred). */
|
|
2060
|
+
readonly readPoint?: {
|
|
2061
|
+
readonly id: string;
|
|
2062
|
+
};
|
|
2063
|
+
/** Business location. */
|
|
2064
|
+
readonly bizLocation?: {
|
|
2065
|
+
readonly id: string;
|
|
2066
|
+
};
|
|
2067
|
+
/** Optropic-specific extension fields. */
|
|
2068
|
+
readonly 'optropic:provenanceEventId'?: string;
|
|
2069
|
+
readonly 'optropic:chainSequence'?: number;
|
|
2070
|
+
readonly 'optropic:eventHash'?: string;
|
|
2071
|
+
}
|
|
2072
|
+
/**
|
|
2073
|
+
* Get the EPCIS 2.0 mapping for an Optropic provenance event type.
|
|
2074
|
+
*
|
|
2075
|
+
* @example
|
|
2076
|
+
* ```typescript
|
|
2077
|
+
* import { mapToEPCIS } from 'optropic';
|
|
2078
|
+
*
|
|
2079
|
+
* const mapping = mapToEPCIS('manufactured');
|
|
2080
|
+
* console.log(mapping.eventType); // 'TransformationEvent'
|
|
2081
|
+
* console.log(mapping.bizStep); // 'urn:epcglobal:cbv:bizstep:commissioning'
|
|
2082
|
+
* ```
|
|
2083
|
+
*/
|
|
2084
|
+
declare function mapToEPCIS(eventType: ProvenanceEventType): EPCISMapping;
|
|
2085
|
+
/**
|
|
2086
|
+
* Get the full mapping table (useful for documentation / UI display).
|
|
2087
|
+
*/
|
|
2088
|
+
declare function getEPCISMappingTable(): Readonly<Record<ProvenanceEventType, EPCISMapping>>;
|
|
2089
|
+
/**
|
|
2090
|
+
* Convert an Optropic ProvenanceEvent into an EPCIS 2.0 JSON-LD event.
|
|
2091
|
+
*
|
|
2092
|
+
* This produces a single EPCIS event object suitable for inclusion
|
|
2093
|
+
* in an EPCISDocument's eventList. The output follows the EPCIS 2.0
|
|
2094
|
+
* JSON/JSON-LD binding specification.
|
|
2095
|
+
*
|
|
2096
|
+
* @param event - Optropic provenance event from the API.
|
|
2097
|
+
* @param options - Optional conversion settings.
|
|
2098
|
+
* @returns EPCIS 2.0 event object.
|
|
2099
|
+
*
|
|
2100
|
+
* @example
|
|
2101
|
+
* ```typescript
|
|
2102
|
+
* const provenanceEvent = await client.provenance.get('evt-123');
|
|
2103
|
+
* const epcisEvent = toEPCISEvent(provenanceEvent);
|
|
2104
|
+
* ```
|
|
2105
|
+
*/
|
|
2106
|
+
declare function toEPCISEvent(event: ProvenanceEvent, options?: ToEPCISEventOptions): EPCISEvent;
|
|
2107
|
+
/**
|
|
2108
|
+
* Wrap one or more EPCIS events in a full EPCISDocument (JSON-LD).
|
|
2109
|
+
*
|
|
2110
|
+
* @param events - Array of EPCIS events.
|
|
2111
|
+
* @returns Complete EPCIS 2.0 document, ready for JSON serialization.
|
|
2112
|
+
*
|
|
2113
|
+
* @example
|
|
2114
|
+
* ```typescript
|
|
2115
|
+
* const chain = await client.provenance.getChain('asset-123');
|
|
2116
|
+
* const events = chain.events.map(e => toEPCISEvent(e));
|
|
2117
|
+
* const doc = buildEPCISDocument(events);
|
|
2118
|
+
* // doc is ready for JSON.stringify() or system ingestion
|
|
2119
|
+
* ```
|
|
2120
|
+
*/
|
|
2121
|
+
declare function buildEPCISDocument(events: EPCISEvent[]): EPCISEventDocument;
|
|
2122
|
+
/**
|
|
2123
|
+
* Convert a full Optropic provenance chain to an EPCIS 2.0 document.
|
|
2124
|
+
*
|
|
2125
|
+
* Convenience method that combines toEPCISEvent + buildEPCISDocument.
|
|
2126
|
+
*
|
|
2127
|
+
* @param events - Array of Optropic provenance events.
|
|
2128
|
+
* @param options - Optional conversion settings.
|
|
2129
|
+
* @returns Complete EPCIS 2.0 JSON-LD document.
|
|
2130
|
+
*/
|
|
2131
|
+
declare function provenanceChainToEPCIS(events: ProvenanceEvent[], options?: ToEPCISEventOptions): EPCISEventDocument;
|
|
2132
|
+
interface ToEPCISEventOptions {
|
|
2133
|
+
/** Timezone offset for eventTime (default: '+00:00'). */
|
|
2134
|
+
readonly timezoneOffset?: string;
|
|
2135
|
+
/** GS1 company prefix for EPC URI generation. */
|
|
2136
|
+
readonly gs1CompanyPrefix?: string;
|
|
2137
|
+
}
|
|
2138
|
+
|
|
2139
|
+
/**
|
|
2140
|
+
* Webhook Signature Verification
|
|
2141
|
+
*
|
|
2142
|
+
* Verifies that incoming webhook payloads were signed by Optropic.
|
|
2143
|
+
* Uses the endpoint secret provided when the webhook was registered.
|
|
2144
|
+
*
|
|
2145
|
+
* @module optropic/webhooks
|
|
2146
|
+
*/
|
|
2147
|
+
interface WebhookVerifyOptions {
|
|
2148
|
+
/** Raw request body (string). Must not be parsed JSON. */
|
|
2149
|
+
readonly payload: string;
|
|
2150
|
+
/** Value of the `X-Optropic-Signature` header. Format: `sha256=<hex>` */
|
|
2151
|
+
readonly signature: string;
|
|
2152
|
+
/** Value of the `X-Optropic-Timestamp` header (unix seconds). */
|
|
1029
2153
|
readonly timestamp: string;
|
|
1030
2154
|
/** The endpoint secret from webhook registration. */
|
|
1031
2155
|
readonly secret: string;
|
|
@@ -1324,6 +2448,1692 @@ declare function createErrorFromResponse(statusCode: number, body: {
|
|
|
1324
2448
|
requestId?: string;
|
|
1325
2449
|
}): OptropicError;
|
|
1326
2450
|
|
|
1327
|
-
|
|
2451
|
+
/**
|
|
2452
|
+
* STANAG 2290 Defence Module - NATO Unique Identification (UID)
|
|
2453
|
+
*
|
|
2454
|
+
* Implements NATO standard for Unique Identification of items per STANAG 2290.
|
|
2455
|
+
* Supports CAGE/NCAGE codes, MIL-STD-130 Data Matrix encoding, and NATO classification.
|
|
2456
|
+
*
|
|
2457
|
+
* @module stanag/uid
|
|
2458
|
+
*/
|
|
2459
|
+
/**
|
|
2460
|
+
* NATO Classification levels per STANAG 2290
|
|
2461
|
+
*/
|
|
2462
|
+
type StanagClassification = 'UNCLASSIFIED' | 'RESTRICTED' | 'CONFIDENTIAL' | 'SECRET' | 'NATO_SECRET' | 'COSMIC_TOP_SECRET';
|
|
2463
|
+
/**
|
|
2464
|
+
* Handling caveats for NATO classified material
|
|
2465
|
+
*/
|
|
2466
|
+
type HandlingCaveat = 'NOFORN' | 'REL_NATO' | 'REL_FVEY' | 'ORCON' | 'PROPIN' | 'RELIDO';
|
|
2467
|
+
/**
|
|
2468
|
+
* UID encoding standards
|
|
2469
|
+
*/
|
|
2470
|
+
type UIDEncoding = 'IUID' | 'UID2' | 'DMRL';
|
|
2471
|
+
/**
|
|
2472
|
+
* NATO UID data structure per STANAG 2290
|
|
2473
|
+
*
|
|
2474
|
+
* @example
|
|
2475
|
+
* ```typescript
|
|
2476
|
+
* const uid: NATOUIDData = {
|
|
2477
|
+
* cage_ncage: '12345',
|
|
2478
|
+
* partNumber: 'LM-9876-C',
|
|
2479
|
+
* serialNumber: 'SN-2024-001',
|
|
2480
|
+
* encoding: 'IUID',
|
|
2481
|
+
* };
|
|
2482
|
+
* ```
|
|
2483
|
+
*/
|
|
2484
|
+
interface NATOUIDData {
|
|
2485
|
+
/**
|
|
2486
|
+
* CAGE (Commercial and Government Entity) or NCAGE code (5 characters)
|
|
2487
|
+
* Required for all NATO UIDs
|
|
2488
|
+
*/
|
|
2489
|
+
cage_ncage: string;
|
|
2490
|
+
/**
|
|
2491
|
+
* Part/model identifier
|
|
2492
|
+
* Unique within the CAGE/NCAGE
|
|
2493
|
+
*/
|
|
2494
|
+
partNumber: string;
|
|
2495
|
+
/**
|
|
2496
|
+
* Unique serial number for this instance
|
|
2497
|
+
*/
|
|
2498
|
+
serialNumber: string;
|
|
2499
|
+
/**
|
|
2500
|
+
* Optional batch or lot identifier
|
|
2501
|
+
*/
|
|
2502
|
+
batchLot?: string;
|
|
2503
|
+
/**
|
|
2504
|
+
* Enterprise ID (DUNS or equivalent)
|
|
2505
|
+
*/
|
|
2506
|
+
enterpriseId?: string;
|
|
2507
|
+
/**
|
|
2508
|
+
* UID encoding standard
|
|
2509
|
+
*/
|
|
2510
|
+
encoding: UIDEncoding;
|
|
2511
|
+
}
|
|
2512
|
+
/**
|
|
2513
|
+
* Batch of NATO UIDs
|
|
2514
|
+
*/
|
|
2515
|
+
interface UIDBatch {
|
|
2516
|
+
/**
|
|
2517
|
+
* Unique batch identifier
|
|
2518
|
+
*/
|
|
2519
|
+
batchId: string;
|
|
2520
|
+
/**
|
|
2521
|
+
* UIDs in this batch
|
|
2522
|
+
*/
|
|
2523
|
+
items: NATOUIDData[];
|
|
2524
|
+
/**
|
|
2525
|
+
* Batch creation timestamp
|
|
2526
|
+
*/
|
|
2527
|
+
createdAt: string;
|
|
2528
|
+
/**
|
|
2529
|
+
* Batch status
|
|
2530
|
+
*/
|
|
2531
|
+
status: 'pending' | 'verified' | 'enrolled' | 'revoked';
|
|
2532
|
+
}
|
|
2533
|
+
/**
|
|
2534
|
+
* Shelf life information per MIL-HDBK-145
|
|
2535
|
+
*/
|
|
2536
|
+
interface ShelfLife {
|
|
2537
|
+
/**
|
|
2538
|
+
* Manufacturing date (ISO 8601)
|
|
2539
|
+
*/
|
|
2540
|
+
manufacturedDate: string;
|
|
2541
|
+
/**
|
|
2542
|
+
* Expiration/shelf life end date (ISO 8601)
|
|
2543
|
+
*/
|
|
2544
|
+
expiryDate: string;
|
|
2545
|
+
/**
|
|
2546
|
+
* Shelf life type per MIL-HDBK-145
|
|
2547
|
+
* TYPE_I: Stable at room temperature
|
|
2548
|
+
* TYPE_II: Requires controlled temperature
|
|
2549
|
+
* TYPE_III: Requires special storage conditions
|
|
2550
|
+
*/
|
|
2551
|
+
type: 'TYPE_I' | 'TYPE_II' | 'TYPE_III';
|
|
2552
|
+
/**
|
|
2553
|
+
* Inspection interval in days
|
|
2554
|
+
*/
|
|
2555
|
+
inspectionIntervalDays?: number;
|
|
2556
|
+
}
|
|
2557
|
+
/**
|
|
2558
|
+
* Defence-specific metadata for NATO assets
|
|
2559
|
+
*/
|
|
2560
|
+
interface DefenceMetadata {
|
|
2561
|
+
/**
|
|
2562
|
+
* NATO classification level
|
|
2563
|
+
*/
|
|
2564
|
+
classification: StanagClassification;
|
|
2565
|
+
/**
|
|
2566
|
+
* Handling caveats
|
|
2567
|
+
*/
|
|
2568
|
+
handlingCaveats: HandlingCaveat[];
|
|
2569
|
+
/**
|
|
2570
|
+
* Organizations/coalitions this is releasable to
|
|
2571
|
+
* e.g., ["NATO", "FVEY", "EU"]
|
|
2572
|
+
*/
|
|
2573
|
+
releasableTo: string[];
|
|
2574
|
+
/**
|
|
2575
|
+
* Shelf life information
|
|
2576
|
+
*/
|
|
2577
|
+
shelfLife?: ShelfLife;
|
|
2578
|
+
/**
|
|
2579
|
+
* Maintenance interval in days
|
|
2580
|
+
*/
|
|
2581
|
+
maintenanceInterval?: number;
|
|
2582
|
+
/**
|
|
2583
|
+
* NATO Stock Number (NSN) - 13 digits
|
|
2584
|
+
*/
|
|
2585
|
+
nsn?: string;
|
|
2586
|
+
/**
|
|
2587
|
+
* Defence Material Reference List reference
|
|
2588
|
+
*/
|
|
2589
|
+
dmrl?: string;
|
|
2590
|
+
}
|
|
2591
|
+
/**
|
|
2592
|
+
* Encodes NATO UID data into MIL-STD-130 Data Matrix format.
|
|
2593
|
+
*
|
|
2594
|
+
* Format: DI "25S" + CAGE/NCAGE + part number + serial number
|
|
2595
|
+
*
|
|
2596
|
+
* @param data - NATO UID data to encode
|
|
2597
|
+
* @returns Encoded NATO UID string
|
|
2598
|
+
*
|
|
2599
|
+
* @example
|
|
2600
|
+
* ```typescript
|
|
2601
|
+
* const encoded = encodeNATOUID({
|
|
2602
|
+
* cage_ncage: '12345',
|
|
2603
|
+
* partNumber: 'LM-9876',
|
|
2604
|
+
* serialNumber: 'SN-2024-001',
|
|
2605
|
+
* encoding: 'IUID',
|
|
2606
|
+
* });
|
|
2607
|
+
* // Returns: "25S12345LM-9876SN-2024-001"
|
|
2608
|
+
* ```
|
|
2609
|
+
*/
|
|
2610
|
+
declare function encodeNATOUID(data: NATOUIDData): string;
|
|
2611
|
+
/**
|
|
2612
|
+
* Decodes a MIL-STD-130 encoded NATO UID back to NATOUIDData.
|
|
2613
|
+
*
|
|
2614
|
+
* @param encoded - Encoded NATO UID string
|
|
2615
|
+
* @returns Decoded NATO UID data
|
|
2616
|
+
* @throws {Error} If the encoded string is invalid
|
|
2617
|
+
*
|
|
2618
|
+
* @example
|
|
2619
|
+
* ```typescript
|
|
2620
|
+
* const decoded = decodeNATOUID("25S12345LM-9876SN-2024-001");
|
|
2621
|
+
* // Returns: {
|
|
2622
|
+
* // cage_ncage: '12345',
|
|
2623
|
+
* // partNumber: 'LM-9876',
|
|
2624
|
+
* // serialNumber: 'SN-2024-001',
|
|
2625
|
+
* // encoding: 'IUID'
|
|
2626
|
+
* // }
|
|
2627
|
+
* ```
|
|
2628
|
+
*/
|
|
2629
|
+
declare function decodeNATOUID(encoded: string): NATOUIDData;
|
|
2630
|
+
/**
|
|
2631
|
+
* Validates a NATO UID string format.
|
|
2632
|
+
*
|
|
2633
|
+
* @param uid - NATO UID string to validate
|
|
2634
|
+
* @returns Validation result with errors if invalid
|
|
2635
|
+
*
|
|
2636
|
+
* @example
|
|
2637
|
+
* ```typescript
|
|
2638
|
+
* const result = validateNATOUID("25S12345LM-9876SN-2024-001");
|
|
2639
|
+
* if (result.valid) {
|
|
2640
|
+
* console.log('Valid NATO UID');
|
|
2641
|
+
* }
|
|
2642
|
+
* ```
|
|
2643
|
+
*/
|
|
2644
|
+
declare function validateNATOUID(uid: string): {
|
|
2645
|
+
valid: boolean;
|
|
2646
|
+
errors: string[];
|
|
2647
|
+
};
|
|
2648
|
+
/**
|
|
2649
|
+
* Maps a NATO UID to Optropic asset creation parameters.
|
|
2650
|
+
*
|
|
2651
|
+
* @param uid - NATO UID data
|
|
2652
|
+
* @returns Object with assetId and metadata for Optropic asset creation
|
|
2653
|
+
*
|
|
2654
|
+
* @example
|
|
2655
|
+
* ```typescript
|
|
2656
|
+
* const mapped = mapNATOUIDToOptropic({
|
|
2657
|
+
* cage_ncage: '12345',
|
|
2658
|
+
* partNumber: 'LM-9876',
|
|
2659
|
+
* serialNumber: 'SN-2024-001',
|
|
2660
|
+
* encoding: 'IUID',
|
|
2661
|
+
* });
|
|
2662
|
+
* ```
|
|
2663
|
+
*/
|
|
2664
|
+
declare function mapNATOUIDToOptropic(uid: NATOUIDData): {
|
|
2665
|
+
assetId: string;
|
|
2666
|
+
metadata: Record<string, unknown>;
|
|
2667
|
+
};
|
|
2668
|
+
/**
|
|
2669
|
+
* Maps Optropic asset data back to NATO UID format.
|
|
2670
|
+
*
|
|
2671
|
+
* @param assetId - The Optropic asset ID
|
|
2672
|
+
* @param metadata - Asset metadata
|
|
2673
|
+
* @returns NATO UID data
|
|
2674
|
+
* @throws {Error} If metadata is missing required fields
|
|
2675
|
+
*/
|
|
2676
|
+
declare function mapOptropicToNATOUID(_assetId: string, metadata: Record<string, unknown>): NATOUIDData;
|
|
2677
|
+
/**
|
|
2678
|
+
* Builds defence metadata for a NATO asset.
|
|
2679
|
+
*
|
|
2680
|
+
* @param classification - NATO classification level
|
|
2681
|
+
* @param caveats - Optional handling caveats
|
|
2682
|
+
* @param shelfLife - Optional shelf life information
|
|
2683
|
+
* @returns Complete defence metadata
|
|
2684
|
+
*
|
|
2685
|
+
* @example
|
|
2686
|
+
* ```typescript
|
|
2687
|
+
* const metadata = buildDefenceMetadata('CONFIDENTIAL', ['NOFORN'], {
|
|
2688
|
+
* manufacturedDate: '2024-01-01T00:00:00Z',
|
|
2689
|
+
* expiryDate: '2026-01-01T00:00:00Z',
|
|
2690
|
+
* type: 'TYPE_I',
|
|
2691
|
+
* });
|
|
2692
|
+
* ```
|
|
2693
|
+
*/
|
|
2694
|
+
declare function buildDefenceMetadata(classification: StanagClassification, caveats?: HandlingCaveat[], shelfLife?: ShelfLife): DefenceMetadata;
|
|
2695
|
+
/**
|
|
2696
|
+
* Validates that a metadata/classification combination is consistent
|
|
2697
|
+
*
|
|
2698
|
+
* @param metadata - Defence metadata to validate
|
|
2699
|
+
* @returns Validation result
|
|
2700
|
+
*/
|
|
2701
|
+
declare function validateDefenceMetadata(metadata: DefenceMetadata): {
|
|
2702
|
+
valid: boolean;
|
|
2703
|
+
errors: string[];
|
|
2704
|
+
};
|
|
2705
|
+
|
|
2706
|
+
/**
|
|
2707
|
+
* STANAG 2106 Supply Chain & Logistics Module
|
|
2708
|
+
*
|
|
2709
|
+
* Implements NATO supply chain tracking and logistics movement mapping
|
|
2710
|
+
* per STANAG 2106 and related standards.
|
|
2711
|
+
*
|
|
2712
|
+
* @module stanag/logistics
|
|
2713
|
+
*/
|
|
2714
|
+
/**
|
|
2715
|
+
* NATO Supply Classification (I-X)
|
|
2716
|
+
*/
|
|
2717
|
+
type SupplyClass = 'I' | 'II' | 'III' | 'IV' | 'V' | 'VI' | 'VII' | 'VIII' | 'IX' | 'X';
|
|
2718
|
+
/**
|
|
2719
|
+
* Priority designator for logistics movements
|
|
2720
|
+
*/
|
|
2721
|
+
type PriorityDesignator = 'IMMEDIATE' | 'PRIORITY' | 'ROUTINE' | 'DEFERRED';
|
|
2722
|
+
/**
|
|
2723
|
+
* Logistics movement type
|
|
2724
|
+
*/
|
|
2725
|
+
type LogisticsMovementType = 'manufacture' | 'receipt' | 'inspection' | 'storage' | 'issue' | 'transport' | 'delivery' | 'maintenance' | 'repair' | 'disposal' | 'destruction' | 'transfer' | 'inventory';
|
|
2726
|
+
/**
|
|
2727
|
+
* Condition status of equipment
|
|
2728
|
+
*/
|
|
2729
|
+
type ConditionStatus = 'serviceable' | 'unserviceable' | 'condemned' | 'obsolete' | 'pending_inspection' | 'under_maintenance' | 'reparable';
|
|
2730
|
+
/**
|
|
2731
|
+
* NATO Logistics Movement Record per STANAG 2106
|
|
2732
|
+
*
|
|
2733
|
+
* @example
|
|
2734
|
+
* ```typescript
|
|
2735
|
+
* const movement: LogisticsMovement = {
|
|
2736
|
+
* movementId: 'LM-2024-001',
|
|
2737
|
+
* itemUID: '25S12345LM-9876SN-001',
|
|
2738
|
+
* movementType: 'receipt',
|
|
2739
|
+
* supplyClass: 'VII',
|
|
2740
|
+
* priority: 'PRIORITY',
|
|
2741
|
+
* location: {
|
|
2742
|
+
* facility: 'NATO Base Bydgoszcz',
|
|
2743
|
+
* coordinates: { lat: 52.1613, lon: 23.1360 },
|
|
2744
|
+
* },
|
|
2745
|
+
* timestamp: '2024-03-31T14:30:00Z',
|
|
2746
|
+
* condition: 'serviceable',
|
|
2747
|
+
* custodian: 'Polish Armed Forces',
|
|
2748
|
+
* };
|
|
2749
|
+
* ```
|
|
2750
|
+
*/
|
|
2751
|
+
interface LogisticsMovement {
|
|
2752
|
+
/**
|
|
2753
|
+
* Unique movement identifier
|
|
2754
|
+
*/
|
|
2755
|
+
movementId: string;
|
|
2756
|
+
/**
|
|
2757
|
+
* NATO UID of the item
|
|
2758
|
+
*/
|
|
2759
|
+
itemUID: string;
|
|
2760
|
+
/**
|
|
2761
|
+
* Type of movement
|
|
2762
|
+
*/
|
|
2763
|
+
movementType: LogisticsMovementType;
|
|
2764
|
+
/**
|
|
2765
|
+
* NATO supply class (I-X)
|
|
2766
|
+
*/
|
|
2767
|
+
supplyClass: SupplyClass;
|
|
2768
|
+
/**
|
|
2769
|
+
* Priority of this movement
|
|
2770
|
+
*/
|
|
2771
|
+
priority: PriorityDesignator;
|
|
2772
|
+
/**
|
|
2773
|
+
* Location information
|
|
2774
|
+
*/
|
|
2775
|
+
location: {
|
|
2776
|
+
facility?: string;
|
|
2777
|
+
coordinates?: {
|
|
2778
|
+
lat: number;
|
|
2779
|
+
lon: number;
|
|
2780
|
+
};
|
|
2781
|
+
militaryGrid?: string;
|
|
2782
|
+
};
|
|
2783
|
+
/**
|
|
2784
|
+
* Timestamp of movement (ISO 8601)
|
|
2785
|
+
*/
|
|
2786
|
+
timestamp: string;
|
|
2787
|
+
/**
|
|
2788
|
+
* Equipment condition status
|
|
2789
|
+
*/
|
|
2790
|
+
condition: ConditionStatus;
|
|
2791
|
+
/**
|
|
2792
|
+
* Custodian/responsible party
|
|
2793
|
+
*/
|
|
2794
|
+
custodian: string;
|
|
2795
|
+
/**
|
|
2796
|
+
* Optional remarks
|
|
2797
|
+
*/
|
|
2798
|
+
remarks?: string;
|
|
2799
|
+
/**
|
|
2800
|
+
* Authorized by (person/unit)
|
|
2801
|
+
*/
|
|
2802
|
+
authorizedBy?: string;
|
|
2803
|
+
/**
|
|
2804
|
+
* Transport method if applicable
|
|
2805
|
+
*/
|
|
2806
|
+
transportMethod?: 'air' | 'sea' | 'rail' | 'road' | 'pipeline' | 'other';
|
|
2807
|
+
/**
|
|
2808
|
+
* Receiving party (if applicable)
|
|
2809
|
+
*/
|
|
2810
|
+
receivingParty?: string;
|
|
2811
|
+
}
|
|
2812
|
+
/**
|
|
2813
|
+
* Readiness thresholds for evaluating supply chain status
|
|
2814
|
+
*/
|
|
2815
|
+
interface ReadinessThresholds {
|
|
2816
|
+
/**
|
|
2817
|
+
* Maximum age of inventory without inspection (days)
|
|
2818
|
+
*/
|
|
2819
|
+
maxInventoryAgeDays?: number;
|
|
2820
|
+
/**
|
|
2821
|
+
* Maximum allowed unserviceable percentage
|
|
2822
|
+
*/
|
|
2823
|
+
maxUnserviceablePercent?: number;
|
|
2824
|
+
/**
|
|
2825
|
+
* Required maintenance compliance percentage
|
|
2826
|
+
*/
|
|
2827
|
+
requiredMaintenancePercent?: number;
|
|
2828
|
+
/**
|
|
2829
|
+
* Maximum transport time (hours)
|
|
2830
|
+
*/
|
|
2831
|
+
maxTransportHours?: number;
|
|
2832
|
+
}
|
|
2833
|
+
/**
|
|
2834
|
+
* Readiness score from logistics analysis
|
|
2835
|
+
*/
|
|
2836
|
+
interface ReadinessScore {
|
|
2837
|
+
/**
|
|
2838
|
+
* Overall readiness percentage (0-100)
|
|
2839
|
+
*/
|
|
2840
|
+
overall: number;
|
|
2841
|
+
/**
|
|
2842
|
+
* Serviceable inventory percentage
|
|
2843
|
+
*/
|
|
2844
|
+
serviceablePercent: number;
|
|
2845
|
+
/**
|
|
2846
|
+
* Maintenance compliance percentage
|
|
2847
|
+
*/
|
|
2848
|
+
maintenanceCompliance: number;
|
|
2849
|
+
/**
|
|
2850
|
+
* Days since last inspection (all items)
|
|
2851
|
+
*/
|
|
2852
|
+
daysSinceInspection: number;
|
|
2853
|
+
/**
|
|
2854
|
+
* Transport efficiency score
|
|
2855
|
+
*/
|
|
2856
|
+
transportEfficiency: number;
|
|
2857
|
+
/**
|
|
2858
|
+
* Recommendations for readiness improvement
|
|
2859
|
+
*/
|
|
2860
|
+
recommendations: string[];
|
|
2861
|
+
/**
|
|
2862
|
+
* Assessment timestamp
|
|
2863
|
+
*/
|
|
2864
|
+
assessmentAt: string;
|
|
2865
|
+
}
|
|
2866
|
+
/**
|
|
2867
|
+
* Maps a NATO logistics movement to an Optropic ProvenanceEvent.
|
|
2868
|
+
*
|
|
2869
|
+
* Creates a provenance event from a logistics movement record for
|
|
2870
|
+
* integration with Optropic's provenance tracking system.
|
|
2871
|
+
*
|
|
2872
|
+
* @param movement - NATO logistics movement
|
|
2873
|
+
* @returns Optropic provenance event
|
|
2874
|
+
*
|
|
2875
|
+
* @example
|
|
2876
|
+
* ```typescript
|
|
2877
|
+
* const movement: LogisticsMovement = {
|
|
2878
|
+
* movementId: 'LM-2024-001',
|
|
2879
|
+
* itemUID: '25S12345LM-9876SN-001',
|
|
2880
|
+
* movementType: 'receipt',
|
|
2881
|
+
* supplyClass: 'VII',
|
|
2882
|
+
* priority: 'PRIORITY',
|
|
2883
|
+
* location: { facility: 'NATO Base' },
|
|
2884
|
+
* timestamp: '2024-03-31T14:30:00Z',
|
|
2885
|
+
* condition: 'serviceable',
|
|
2886
|
+
* custodian: 'Polish Armed Forces',
|
|
2887
|
+
* };
|
|
2888
|
+
*
|
|
2889
|
+
* const event = mapMovementToProvenance(movement);
|
|
2890
|
+
* ```
|
|
2891
|
+
*/
|
|
2892
|
+
interface ProvenanceMappingResult {
|
|
2893
|
+
eventType: string;
|
|
2894
|
+
timestamp: string;
|
|
2895
|
+
actor: string;
|
|
2896
|
+
location?: {
|
|
2897
|
+
facility?: string;
|
|
2898
|
+
coordinates?: {
|
|
2899
|
+
lat: number;
|
|
2900
|
+
lng: number;
|
|
2901
|
+
};
|
|
2902
|
+
};
|
|
2903
|
+
metadata: Record<string, unknown>;
|
|
2904
|
+
}
|
|
2905
|
+
declare function mapMovementToProvenance(movement: LogisticsMovement): ProvenanceMappingResult;
|
|
2906
|
+
/**
|
|
2907
|
+
* Calculates readiness score from a series of logistics movements.
|
|
2908
|
+
*
|
|
2909
|
+
* Evaluates supply chain health and operational readiness based on:
|
|
2910
|
+
* - Equipment condition status
|
|
2911
|
+
* - Inspection frequency
|
|
2912
|
+
* - Maintenance compliance
|
|
2913
|
+
* - Transport efficiency
|
|
2914
|
+
*
|
|
2915
|
+
* @param movements - Array of logistics movements
|
|
2916
|
+
* @param thresholds - Optional readiness thresholds
|
|
2917
|
+
* @returns Readiness score and recommendations
|
|
2918
|
+
*
|
|
2919
|
+
* @example
|
|
2920
|
+
* ```typescript
|
|
2921
|
+
* const movements: LogisticsMovement[] = [...];
|
|
2922
|
+
* const score = calculateReadiness(movements, {
|
|
2923
|
+
* maxInventoryAgeDays: 365,
|
|
2924
|
+
* maxUnserviceablePercent: 10,
|
|
2925
|
+
* requiredMaintenancePercent: 95,
|
|
2926
|
+
* });
|
|
2927
|
+
* console.log(`Readiness: ${score.overall}%`);
|
|
2928
|
+
* ```
|
|
2929
|
+
*/
|
|
2930
|
+
declare function calculateReadiness(movements: LogisticsMovement[], thresholds?: ReadinessThresholds): ReadinessScore;
|
|
2931
|
+
/**
|
|
2932
|
+
* Validates a logistics movement record
|
|
2933
|
+
*
|
|
2934
|
+
* @param movement - Logistics movement to validate
|
|
2935
|
+
* @returns Validation result
|
|
2936
|
+
*/
|
|
2937
|
+
declare function validateLogisticsMovement(movement: LogisticsMovement): {
|
|
2938
|
+
valid: boolean;
|
|
2939
|
+
errors: string[];
|
|
2940
|
+
};
|
|
2941
|
+
|
|
2942
|
+
/**
|
|
2943
|
+
* Multi-Tenant Platform Module
|
|
2944
|
+
*
|
|
2945
|
+
* Provides complete multi-tenant organization management, RLS (Row-Level Security),
|
|
2946
|
+
* member management, and admin APIs for enterprise Optropic deployments.
|
|
2947
|
+
*
|
|
2948
|
+
* @module multi-tenant/platform
|
|
2949
|
+
*/
|
|
2950
|
+
/**
|
|
2951
|
+
* Organization plan tier
|
|
2952
|
+
*/
|
|
2953
|
+
type OrgPlanTier = 'starter' | 'professional' | 'enterprise' | 'sovereign';
|
|
2954
|
+
/**
|
|
2955
|
+
* Organization status
|
|
2956
|
+
*/
|
|
2957
|
+
type OrgStatus = 'active' | 'suspended' | 'pending';
|
|
2958
|
+
/**
|
|
2959
|
+
* Tenant role with associated permission levels
|
|
2960
|
+
*/
|
|
2961
|
+
type TenantRole = 'owner' | 'admin' | 'member' | 'viewer' | 'auditor';
|
|
2962
|
+
/**
|
|
2963
|
+
* Member status in tenant
|
|
2964
|
+
*/
|
|
2965
|
+
type MemberStatus = 'active' | 'invited' | 'suspended';
|
|
2966
|
+
/**
|
|
2967
|
+
* Invite status
|
|
2968
|
+
*/
|
|
2969
|
+
type InviteStatus = 'pending' | 'accepted' | 'expired' | 'revoked';
|
|
2970
|
+
/**
|
|
2971
|
+
* Data residency requirement per compliance framework
|
|
2972
|
+
*/
|
|
2973
|
+
type DataResidency = 'eu' | 'eu-sovereign' | 'de-only';
|
|
2974
|
+
/**
|
|
2975
|
+
* RLS resource type
|
|
2976
|
+
*/
|
|
2977
|
+
type RLSResourceType = 'assets' | 'documents' | 'keys' | 'audit' | 'provenance';
|
|
2978
|
+
/**
|
|
2979
|
+
* RLS action
|
|
2980
|
+
*/
|
|
2981
|
+
type RLSAction = 'read' | 'write' | 'delete' | 'admin';
|
|
2982
|
+
/**
|
|
2983
|
+
* RLS condition operator
|
|
2984
|
+
*/
|
|
2985
|
+
type RLSOperator = 'eq' | 'neq' | 'in' | 'not_in' | 'contains' | 'starts_with' | 'gt' | 'lt';
|
|
2986
|
+
/**
|
|
2987
|
+
* Organization settings with compliance and security controls
|
|
2988
|
+
*
|
|
2989
|
+
* @example
|
|
2990
|
+
* ```typescript
|
|
2991
|
+
* const settings: OrganizationSettings = {
|
|
2992
|
+
* defaultClassification: 'CONFIDENTIAL',
|
|
2993
|
+
* dataResidency: 'eu-sovereign',
|
|
2994
|
+
* retentionDays: 2555,
|
|
2995
|
+
* mfaRequired: true,
|
|
2996
|
+
* ipAllowList: ['10.0.0.0/8'],
|
|
2997
|
+
* webhookSigningAlgorithm: 'ed25519',
|
|
2998
|
+
* };
|
|
2999
|
+
* ```
|
|
3000
|
+
*/
|
|
3001
|
+
interface OrganizationSettings {
|
|
3002
|
+
/**
|
|
3003
|
+
* Default classification level for new assets
|
|
3004
|
+
*/
|
|
3005
|
+
defaultClassification: string;
|
|
3006
|
+
/**
|
|
3007
|
+
* Required data residency location
|
|
3008
|
+
*/
|
|
3009
|
+
dataResidency: DataResidency;
|
|
3010
|
+
/**
|
|
3011
|
+
* Data retention period in days
|
|
3012
|
+
*/
|
|
3013
|
+
retentionDays: number;
|
|
3014
|
+
/**
|
|
3015
|
+
* Require MFA for all users
|
|
3016
|
+
*/
|
|
3017
|
+
mfaRequired: boolean;
|
|
3018
|
+
/**
|
|
3019
|
+
* Allowed IP ranges (CIDR notation)
|
|
3020
|
+
*/
|
|
3021
|
+
ipAllowList?: string[];
|
|
3022
|
+
/**
|
|
3023
|
+
* Webhook signing algorithm
|
|
3024
|
+
*/
|
|
3025
|
+
webhookSigningAlgorithm: 'hmac-sha256' | 'ed25519';
|
|
3026
|
+
/**
|
|
3027
|
+
* Custom metadata
|
|
3028
|
+
*/
|
|
3029
|
+
customMetadata?: Record<string, unknown>;
|
|
3030
|
+
}
|
|
3031
|
+
/**
|
|
3032
|
+
* Organization entity representing a tenant
|
|
3033
|
+
*
|
|
3034
|
+
* @example
|
|
3035
|
+
* ```typescript
|
|
3036
|
+
* const org: Organization = {
|
|
3037
|
+
* id: 'org_12345',
|
|
3038
|
+
* name: 'ACME Corp',
|
|
3039
|
+
* slug: 'acme-corp',
|
|
3040
|
+
* plan: 'enterprise',
|
|
3041
|
+
* status: 'active',
|
|
3042
|
+
* settings: { ... },
|
|
3043
|
+
* createdAt: '2024-01-01T00:00:00Z',
|
|
3044
|
+
* updatedAt: '2024-03-31T00:00:00Z',
|
|
3045
|
+
* };
|
|
3046
|
+
* ```
|
|
3047
|
+
*/
|
|
3048
|
+
interface Organization {
|
|
3049
|
+
/**
|
|
3050
|
+
* Unique organization ID
|
|
3051
|
+
*/
|
|
3052
|
+
id: string;
|
|
3053
|
+
/**
|
|
3054
|
+
* Organization display name
|
|
3055
|
+
*/
|
|
3056
|
+
name: string;
|
|
3057
|
+
/**
|
|
3058
|
+
* URL-safe slug for the organization
|
|
3059
|
+
*/
|
|
3060
|
+
slug: string;
|
|
3061
|
+
/**
|
|
3062
|
+
* Service plan tier
|
|
3063
|
+
*/
|
|
3064
|
+
plan: OrgPlanTier;
|
|
3065
|
+
/**
|
|
3066
|
+
* Current status
|
|
3067
|
+
*/
|
|
3068
|
+
status: OrgStatus;
|
|
3069
|
+
/**
|
|
3070
|
+
* Organization settings
|
|
3071
|
+
*/
|
|
3072
|
+
settings: OrganizationSettings;
|
|
3073
|
+
/**
|
|
3074
|
+
* Creation timestamp
|
|
3075
|
+
*/
|
|
3076
|
+
createdAt: string;
|
|
3077
|
+
/**
|
|
3078
|
+
* Last update timestamp
|
|
3079
|
+
*/
|
|
3080
|
+
updatedAt: string;
|
|
3081
|
+
}
|
|
3082
|
+
/**
|
|
3083
|
+
* Tenant member with role and permissions
|
|
3084
|
+
*
|
|
3085
|
+
* @example
|
|
3086
|
+
* ```typescript
|
|
3087
|
+
* const member: TenantMember = {
|
|
3088
|
+
* userId: 'user_abc123',
|
|
3089
|
+
* email: 'alice@example.com',
|
|
3090
|
+
* role: 'admin',
|
|
3091
|
+
* status: 'active',
|
|
3092
|
+
* joinedAt: '2024-01-15T00:00:00Z',
|
|
3093
|
+
* permissions: ['assets:read', 'assets:write', 'audit:read'],
|
|
3094
|
+
* };
|
|
3095
|
+
* ```
|
|
3096
|
+
*/
|
|
3097
|
+
interface TenantMember {
|
|
3098
|
+
/**
|
|
3099
|
+
* Unique user ID
|
|
3100
|
+
*/
|
|
3101
|
+
userId: string;
|
|
3102
|
+
/**
|
|
3103
|
+
* User email address
|
|
3104
|
+
*/
|
|
3105
|
+
email: string;
|
|
3106
|
+
/**
|
|
3107
|
+
* Role in the tenant
|
|
3108
|
+
*/
|
|
3109
|
+
role: TenantRole;
|
|
3110
|
+
/**
|
|
3111
|
+
* Current membership status
|
|
3112
|
+
*/
|
|
3113
|
+
status: MemberStatus;
|
|
3114
|
+
/**
|
|
3115
|
+
* When user joined
|
|
3116
|
+
*/
|
|
3117
|
+
joinedAt: string;
|
|
3118
|
+
/**
|
|
3119
|
+
* Last active timestamp
|
|
3120
|
+
*/
|
|
3121
|
+
lastActiveAt?: string;
|
|
3122
|
+
/**
|
|
3123
|
+
* Explicit permissions (overrides role defaults)
|
|
3124
|
+
*/
|
|
3125
|
+
permissions: string[];
|
|
3126
|
+
}
|
|
3127
|
+
/**
|
|
3128
|
+
* Tenant invitation to join an organization
|
|
3129
|
+
*
|
|
3130
|
+
* @example
|
|
3131
|
+
* ```typescript
|
|
3132
|
+
* const invite: TenantInvite = {
|
|
3133
|
+
* id: 'invite_xyz789',
|
|
3134
|
+
* email: 'newuser@example.com',
|
|
3135
|
+
* role: 'member',
|
|
3136
|
+
* invitedBy: 'user_abc123',
|
|
3137
|
+
* expiresAt: '2024-04-30T00:00:00Z',
|
|
3138
|
+
* status: 'pending',
|
|
3139
|
+
* };
|
|
3140
|
+
* ```
|
|
3141
|
+
*/
|
|
3142
|
+
interface TenantInvite {
|
|
3143
|
+
/**
|
|
3144
|
+
* Unique invite ID
|
|
3145
|
+
*/
|
|
3146
|
+
id: string;
|
|
3147
|
+
/**
|
|
3148
|
+
* Email address being invited
|
|
3149
|
+
*/
|
|
3150
|
+
email: string;
|
|
3151
|
+
/**
|
|
3152
|
+
* Role to assign on acceptance
|
|
3153
|
+
*/
|
|
3154
|
+
role: TenantRole;
|
|
3155
|
+
/**
|
|
3156
|
+
* User who issued the invite
|
|
3157
|
+
*/
|
|
3158
|
+
invitedBy: string;
|
|
3159
|
+
/**
|
|
3160
|
+
* Invite expiration time
|
|
3161
|
+
*/
|
|
3162
|
+
expiresAt: string;
|
|
3163
|
+
/**
|
|
3164
|
+
* Current invite status
|
|
3165
|
+
*/
|
|
3166
|
+
status: InviteStatus;
|
|
3167
|
+
}
|
|
3168
|
+
/**
|
|
3169
|
+
* RLS condition for access control
|
|
3170
|
+
*
|
|
3171
|
+
* @example
|
|
3172
|
+
* ```typescript
|
|
3173
|
+
* const condition: RLSCondition = {
|
|
3174
|
+
* field: 'tenantId',
|
|
3175
|
+
* operator: 'eq',
|
|
3176
|
+
* value: 'org_12345',
|
|
3177
|
+
* };
|
|
3178
|
+
* ```
|
|
3179
|
+
*/
|
|
3180
|
+
interface RLSCondition {
|
|
3181
|
+
/**
|
|
3182
|
+
* Field name to evaluate
|
|
3183
|
+
*/
|
|
3184
|
+
field: string;
|
|
3185
|
+
/**
|
|
3186
|
+
* Comparison operator
|
|
3187
|
+
*/
|
|
3188
|
+
operator: RLSOperator;
|
|
3189
|
+
/**
|
|
3190
|
+
* Value(s) to compare against
|
|
3191
|
+
*/
|
|
3192
|
+
value: string | string[] | number;
|
|
3193
|
+
}
|
|
3194
|
+
/**
|
|
3195
|
+
* Row-Level Security (RLS) Policy for fine-grained access control
|
|
3196
|
+
*
|
|
3197
|
+
* @example
|
|
3198
|
+
* ```typescript
|
|
3199
|
+
* const policy: RLSPolicy = {
|
|
3200
|
+
* id: 'policy_123',
|
|
3201
|
+
* tenantId: 'org_12345',
|
|
3202
|
+
* resourceType: 'assets',
|
|
3203
|
+
* action: 'read',
|
|
3204
|
+
* condition: { field: 'tenantId', operator: 'eq', value: 'org_12345' },
|
|
3205
|
+
* priority: 100,
|
|
3206
|
+
* enabled: true,
|
|
3207
|
+
* };
|
|
3208
|
+
* ```
|
|
3209
|
+
*/
|
|
3210
|
+
interface RLSPolicy {
|
|
3211
|
+
/**
|
|
3212
|
+
* Unique policy ID
|
|
3213
|
+
*/
|
|
3214
|
+
id: string;
|
|
3215
|
+
/**
|
|
3216
|
+
* Tenant this policy applies to
|
|
3217
|
+
*/
|
|
3218
|
+
tenantId: string;
|
|
3219
|
+
/**
|
|
3220
|
+
* Resource type being protected
|
|
3221
|
+
*/
|
|
3222
|
+
resourceType: RLSResourceType;
|
|
3223
|
+
/**
|
|
3224
|
+
* Action being controlled
|
|
3225
|
+
*/
|
|
3226
|
+
action: RLSAction;
|
|
3227
|
+
/**
|
|
3228
|
+
* Condition to enforce
|
|
3229
|
+
*/
|
|
3230
|
+
condition: RLSCondition;
|
|
3231
|
+
/**
|
|
3232
|
+
* Policy priority (higher = evaluated first)
|
|
3233
|
+
*/
|
|
3234
|
+
priority: number;
|
|
3235
|
+
/**
|
|
3236
|
+
* Whether this policy is active
|
|
3237
|
+
*/
|
|
3238
|
+
enabled: boolean;
|
|
3239
|
+
}
|
|
3240
|
+
/**
|
|
3241
|
+
* Usage quota and limit tracking per tenant
|
|
3242
|
+
*
|
|
3243
|
+
* @example
|
|
3244
|
+
* ```typescript
|
|
3245
|
+
* const quota: TenantUsageQuota = {
|
|
3246
|
+
* tenantId: 'org_12345',
|
|
3247
|
+
* period: 'monthly',
|
|
3248
|
+
* limits: { assets: 10000, verifications: 100000, apiCalls: 1000000, storage_mb: 1048576 },
|
|
3249
|
+
* current: { assets: 2500, verifications: 45000, apiCalls: 500000, storage_mb: 512000 },
|
|
3250
|
+
* resetAt: '2024-04-01T00:00:00Z',
|
|
3251
|
+
* };
|
|
3252
|
+
* ```
|
|
3253
|
+
*/
|
|
3254
|
+
interface TenantUsageQuota {
|
|
3255
|
+
/**
|
|
3256
|
+
* Tenant ID
|
|
3257
|
+
*/
|
|
3258
|
+
tenantId: string;
|
|
3259
|
+
/**
|
|
3260
|
+
* Quota period
|
|
3261
|
+
*/
|
|
3262
|
+
period: 'daily' | 'monthly';
|
|
3263
|
+
/**
|
|
3264
|
+
* Resource limits
|
|
3265
|
+
*/
|
|
3266
|
+
limits: {
|
|
3267
|
+
assets: number;
|
|
3268
|
+
verifications: number;
|
|
3269
|
+
apiCalls: number;
|
|
3270
|
+
storage_mb: number;
|
|
3271
|
+
};
|
|
3272
|
+
/**
|
|
3273
|
+
* Current usage
|
|
3274
|
+
*/
|
|
3275
|
+
current: {
|
|
3276
|
+
assets: number;
|
|
3277
|
+
verifications: number;
|
|
3278
|
+
apiCalls: number;
|
|
3279
|
+
storage_mb: number;
|
|
3280
|
+
};
|
|
3281
|
+
/**
|
|
3282
|
+
* When quota resets
|
|
3283
|
+
*/
|
|
3284
|
+
resetAt: string;
|
|
3285
|
+
}
|
|
3286
|
+
/**
|
|
3287
|
+
* Parameters for creating a new organization
|
|
3288
|
+
*/
|
|
3289
|
+
interface CreateOrganizationParams {
|
|
3290
|
+
name: string;
|
|
3291
|
+
slug: string;
|
|
3292
|
+
plan: OrgPlanTier;
|
|
3293
|
+
settings: OrganizationSettings;
|
|
3294
|
+
}
|
|
3295
|
+
/**
|
|
3296
|
+
* Parameters for updating organization
|
|
3297
|
+
*/
|
|
3298
|
+
interface UpdateOrganizationParams {
|
|
3299
|
+
name?: string;
|
|
3300
|
+
plan?: OrgPlanTier;
|
|
3301
|
+
status?: OrgStatus;
|
|
3302
|
+
settings?: Partial<OrganizationSettings>;
|
|
3303
|
+
}
|
|
3304
|
+
/**
|
|
3305
|
+
* Creates a new organization
|
|
3306
|
+
*
|
|
3307
|
+
* @param params - Organization creation parameters
|
|
3308
|
+
* @returns Created organization
|
|
3309
|
+
*
|
|
3310
|
+
* @example
|
|
3311
|
+
* ```typescript
|
|
3312
|
+
* const org = await createOrganization({
|
|
3313
|
+
* name: 'ACME Corp',
|
|
3314
|
+
* slug: 'acme-corp',
|
|
3315
|
+
* plan: 'enterprise',
|
|
3316
|
+
* settings: {
|
|
3317
|
+
* defaultClassification: 'CONFIDENTIAL',
|
|
3318
|
+
* dataResidency: 'eu-sovereign',
|
|
3319
|
+
* retentionDays: 2555,
|
|
3320
|
+
* mfaRequired: true,
|
|
3321
|
+
* webhookSigningAlgorithm: 'ed25519',
|
|
3322
|
+
* },
|
|
3323
|
+
* });
|
|
3324
|
+
* ```
|
|
3325
|
+
*/
|
|
3326
|
+
declare function createOrganization(params: CreateOrganizationParams): Promise<Organization>;
|
|
3327
|
+
/**
|
|
3328
|
+
* Retrieves an organization by ID
|
|
3329
|
+
*
|
|
3330
|
+
* @param orgId - Organization ID
|
|
3331
|
+
* @returns Organization details
|
|
3332
|
+
*/
|
|
3333
|
+
declare function getOrganization(orgId: string): Promise<Organization>;
|
|
3334
|
+
/**
|
|
3335
|
+
* Updates an organization's settings
|
|
3336
|
+
*
|
|
3337
|
+
* @param orgId - Organization ID
|
|
3338
|
+
* @param updates - Fields to update
|
|
3339
|
+
* @returns Updated organization
|
|
3340
|
+
*/
|
|
3341
|
+
declare function updateOrganization(orgId: string, updates: UpdateOrganizationParams): Promise<Organization>;
|
|
3342
|
+
/**
|
|
3343
|
+
* Lists all members of an organization
|
|
3344
|
+
*
|
|
3345
|
+
* @param orgId - Organization ID
|
|
3346
|
+
* @returns Array of tenant members
|
|
3347
|
+
*
|
|
3348
|
+
* @example
|
|
3349
|
+
* ```typescript
|
|
3350
|
+
* const members = await listMembers('org_12345');
|
|
3351
|
+
* ```
|
|
3352
|
+
*/
|
|
3353
|
+
declare function listMembers(orgId: string): Promise<TenantMember[]>;
|
|
3354
|
+
/**
|
|
3355
|
+
* Parameters for inviting a member
|
|
3356
|
+
*/
|
|
3357
|
+
interface InviteMemberParams {
|
|
3358
|
+
orgId: string;
|
|
3359
|
+
email: string;
|
|
3360
|
+
role: TenantRole;
|
|
3361
|
+
}
|
|
3362
|
+
/**
|
|
3363
|
+
* Invites a user to join an organization
|
|
3364
|
+
*
|
|
3365
|
+
* @param orgId - Organization ID
|
|
3366
|
+
* @param email - Email to invite
|
|
3367
|
+
* @param role - Role to assign
|
|
3368
|
+
* @returns Created invite
|
|
3369
|
+
*
|
|
3370
|
+
* @example
|
|
3371
|
+
* ```typescript
|
|
3372
|
+
* const invite = await inviteMember('org_12345', 'alice@example.com', 'member');
|
|
3373
|
+
* ```
|
|
3374
|
+
*/
|
|
3375
|
+
declare function inviteMember(orgId: string, email: string, role: TenantRole): Promise<TenantInvite>;
|
|
3376
|
+
/**
|
|
3377
|
+
* Removes a member from an organization
|
|
3378
|
+
*
|
|
3379
|
+
* @param orgId - Organization ID
|
|
3380
|
+
* @param userId - User ID to remove
|
|
3381
|
+
*/
|
|
3382
|
+
declare function removeMember(orgId: string, userId: string): Promise<void>;
|
|
3383
|
+
/**
|
|
3384
|
+
* Updates a member's role
|
|
3385
|
+
*
|
|
3386
|
+
* @param orgId - Organization ID
|
|
3387
|
+
* @param userId - User ID
|
|
3388
|
+
* @param newRole - New role to assign
|
|
3389
|
+
* @returns Updated member
|
|
3390
|
+
*/
|
|
3391
|
+
declare function updateMemberRole(orgId: string, userId: string, newRole: TenantRole): Promise<TenantMember>;
|
|
3392
|
+
/**
|
|
3393
|
+
* Parameters for creating an RLS policy
|
|
3394
|
+
*/
|
|
3395
|
+
interface CreateRLSPolicyParams {
|
|
3396
|
+
tenantId: string;
|
|
3397
|
+
resourceType: RLSResourceType;
|
|
3398
|
+
action: RLSAction;
|
|
3399
|
+
condition: RLSCondition;
|
|
3400
|
+
priority?: number;
|
|
3401
|
+
}
|
|
3402
|
+
/**
|
|
3403
|
+
* Creates a new RLS policy for fine-grained access control
|
|
3404
|
+
*
|
|
3405
|
+
* @param params - Policy parameters
|
|
3406
|
+
* @returns Created policy
|
|
3407
|
+
*
|
|
3408
|
+
* @example
|
|
3409
|
+
* ```typescript
|
|
3410
|
+
* const policy = await createRLSPolicy({
|
|
3411
|
+
* tenantId: 'org_12345',
|
|
3412
|
+
* resourceType: 'assets',
|
|
3413
|
+
* action: 'read',
|
|
3414
|
+
* condition: {
|
|
3415
|
+
* field: 'tenantId',
|
|
3416
|
+
* operator: 'eq',
|
|
3417
|
+
* value: 'org_12345',
|
|
3418
|
+
* },
|
|
3419
|
+
* priority: 100,
|
|
3420
|
+
* });
|
|
3421
|
+
* ```
|
|
3422
|
+
*/
|
|
3423
|
+
declare function createRLSPolicy(params: CreateRLSPolicyParams): Promise<RLSPolicy>;
|
|
3424
|
+
/**
|
|
3425
|
+
* Lists all RLS policies for a tenant
|
|
3426
|
+
*
|
|
3427
|
+
* @param tenantId - Tenant ID
|
|
3428
|
+
* @returns Array of RLS policies
|
|
3429
|
+
*/
|
|
3430
|
+
declare function listRLSPolicies(tenantId: string): Promise<RLSPolicy[]>;
|
|
3431
|
+
/**
|
|
3432
|
+
* Deletes an RLS policy
|
|
3433
|
+
*
|
|
3434
|
+
* @param policyId - Policy ID
|
|
3435
|
+
*/
|
|
3436
|
+
declare function deleteRLSPolicy(policyId: string): Promise<void>;
|
|
3437
|
+
/**
|
|
3438
|
+
* Retrieves usage quota for a tenant
|
|
3439
|
+
*
|
|
3440
|
+
* @param tenantId - Tenant ID
|
|
3441
|
+
* @returns Current usage and limits
|
|
3442
|
+
*
|
|
3443
|
+
* @example
|
|
3444
|
+
* ```typescript
|
|
3445
|
+
* const quota = await getUsageQuota('org_12345');
|
|
3446
|
+
* console.log(`Using ${quota.current.assets}/${quota.limits.assets} assets`);
|
|
3447
|
+
* ```
|
|
3448
|
+
*/
|
|
3449
|
+
declare function getUsageQuota(tenantId: string): Promise<TenantUsageQuota>;
|
|
3450
|
+
/**
|
|
3451
|
+
* Parameters for updating usage quota limits
|
|
3452
|
+
*/
|
|
3453
|
+
interface UpdateUsageQuotaParams {
|
|
3454
|
+
assets?: number;
|
|
3455
|
+
verifications?: number;
|
|
3456
|
+
apiCalls?: number;
|
|
3457
|
+
storage_mb?: number;
|
|
3458
|
+
}
|
|
3459
|
+
/**
|
|
3460
|
+
* Updates usage quota limits (admin only)
|
|
3461
|
+
*
|
|
3462
|
+
* @param tenantId - Tenant ID
|
|
3463
|
+
* @param limits - New limits
|
|
3464
|
+
* @returns Updated quota
|
|
3465
|
+
*/
|
|
3466
|
+
declare function updateUsageQuota(tenantId: string, limits: UpdateUsageQuotaParams): Promise<TenantUsageQuota>;
|
|
3467
|
+
/**
|
|
3468
|
+
* Determines role permissions
|
|
3469
|
+
*
|
|
3470
|
+
* @param role - Tenant role
|
|
3471
|
+
* @returns Array of permission strings
|
|
3472
|
+
*/
|
|
3473
|
+
declare function getRolePermissions(role: TenantRole): string[];
|
|
3474
|
+
|
|
3475
|
+
/**
|
|
3476
|
+
* Partner management for the Optropic Marketplace.
|
|
3477
|
+
* Enables partners to register, authenticate, and manage their marketplace presence.
|
|
3478
|
+
*
|
|
3479
|
+
* @module marketplace/partner
|
|
3480
|
+
*/
|
|
3481
|
+
/**
|
|
3482
|
+
* Partner tier levels determining features and revenue share.
|
|
3483
|
+
*/
|
|
3484
|
+
type PartnerTier = 'bronze' | 'silver' | 'gold' | 'platinum';
|
|
3485
|
+
/**
|
|
3486
|
+
* Partner account types and their capabilities.
|
|
3487
|
+
*/
|
|
3488
|
+
type PartnerType = 'integrator' | 'reseller' | 'oem' | 'consultant';
|
|
3489
|
+
/**
|
|
3490
|
+
* Partner account status.
|
|
3491
|
+
*/
|
|
3492
|
+
type PartnerStatus = 'active' | 'pending' | 'suspended';
|
|
3493
|
+
/**
|
|
3494
|
+
* API scopes that can be granted to a partner.
|
|
3495
|
+
*/
|
|
3496
|
+
type PartnerScope = 'templates:read' | 'templates:write' | 'templates:publish' | 'verify:white_label' | 'verify:co_branded' | 'analytics:own' | 'analytics:aggregate' | 'webhooks:manage' | 'keys:scoped';
|
|
3497
|
+
/**
|
|
3498
|
+
* Complete partner profile with tier, status, and permissions.
|
|
3499
|
+
*/
|
|
3500
|
+
interface PartnerProfile {
|
|
3501
|
+
/** Unique partner identifier */
|
|
3502
|
+
id: string;
|
|
3503
|
+
/** Display name */
|
|
3504
|
+
name: string;
|
|
3505
|
+
/** URL-safe slug for partner */
|
|
3506
|
+
slug: string;
|
|
3507
|
+
/** Partner type/business model */
|
|
3508
|
+
type: PartnerType;
|
|
3509
|
+
/** Current account status */
|
|
3510
|
+
status: PartnerStatus;
|
|
3511
|
+
/** Service tier level */
|
|
3512
|
+
tier: PartnerTier;
|
|
3513
|
+
/** Primary contact email */
|
|
3514
|
+
contactEmail: string;
|
|
3515
|
+
/** Company/product website */
|
|
3516
|
+
website?: string;
|
|
3517
|
+
/** Granted API scopes */
|
|
3518
|
+
apiScopes: PartnerScope[];
|
|
3519
|
+
/** Revenue share percentage (0-100) */
|
|
3520
|
+
revenueShare: number;
|
|
3521
|
+
/** Account creation timestamp (ISO 8601) */
|
|
3522
|
+
createdAt: string;
|
|
3523
|
+
/** Last update timestamp (ISO 8601) */
|
|
3524
|
+
updatedAt: string;
|
|
3525
|
+
}
|
|
3526
|
+
/**
|
|
3527
|
+
* Registration payload for new partners.
|
|
3528
|
+
*/
|
|
3529
|
+
interface PartnerRegistration {
|
|
3530
|
+
/** Company/partner name */
|
|
3531
|
+
name: string;
|
|
3532
|
+
/** Business model type */
|
|
3533
|
+
type: PartnerType;
|
|
3534
|
+
/** Contact email for notifications */
|
|
3535
|
+
contactEmail: string;
|
|
3536
|
+
/** Optional website URL */
|
|
3537
|
+
website?: string;
|
|
3538
|
+
/** Requested API scopes */
|
|
3539
|
+
requestedScopes: PartnerScope[];
|
|
3540
|
+
}
|
|
3541
|
+
/**
|
|
3542
|
+
* Partner analytics for a specific period.
|
|
3543
|
+
*/
|
|
3544
|
+
interface PartnerAnalytics {
|
|
3545
|
+
/** Partner ID */
|
|
3546
|
+
partnerId: string;
|
|
3547
|
+
/** Reporting period (ISO month format, e.g., "2026-04") */
|
|
3548
|
+
period: string;
|
|
3549
|
+
/** Number of template downloads in period */
|
|
3550
|
+
templateDownloads: number;
|
|
3551
|
+
/** Number of verifications performed using partner templates */
|
|
3552
|
+
verificationsMade: number;
|
|
3553
|
+
/** Total revenue generated in cents */
|
|
3554
|
+
revenueGenerated: number;
|
|
3555
|
+
/** Active installations of partner templates */
|
|
3556
|
+
activeInstallations: number;
|
|
3557
|
+
}
|
|
3558
|
+
/**
|
|
3559
|
+
* Request to update partner profile settings.
|
|
3560
|
+
*/
|
|
3561
|
+
interface UpdatePartnerParams {
|
|
3562
|
+
/** Display name */
|
|
3563
|
+
name?: string;
|
|
3564
|
+
/** Contact email */
|
|
3565
|
+
contactEmail?: string;
|
|
3566
|
+
/** Website URL */
|
|
3567
|
+
website?: string;
|
|
3568
|
+
/** Tier upgrade request */
|
|
3569
|
+
tier?: PartnerTier;
|
|
3570
|
+
}
|
|
3571
|
+
/**
|
|
3572
|
+
* API key for partner authentication.
|
|
3573
|
+
*/
|
|
3574
|
+
interface PartnerApiKey {
|
|
3575
|
+
/** Key identifier */
|
|
3576
|
+
id: string;
|
|
3577
|
+
/** Full API key (only shown at creation) */
|
|
3578
|
+
key?: string;
|
|
3579
|
+
/** Masked key for display */
|
|
3580
|
+
maskedKey: string;
|
|
3581
|
+
/** Associated partner ID */
|
|
3582
|
+
partnerId: string;
|
|
3583
|
+
/** Allowed scopes for this key */
|
|
3584
|
+
scopes: PartnerScope[];
|
|
3585
|
+
/** Key creation timestamp */
|
|
3586
|
+
createdAt: string;
|
|
3587
|
+
/** Key expiration timestamp (optional) */
|
|
3588
|
+
expiresAt?: string;
|
|
3589
|
+
/** Last usage timestamp */
|
|
3590
|
+
lastUsedAt?: string;
|
|
3591
|
+
}
|
|
3592
|
+
/**
|
|
3593
|
+
* Response from partner registration.
|
|
3594
|
+
*/
|
|
3595
|
+
interface PartnerRegistrationResult {
|
|
3596
|
+
/** Created partner profile */
|
|
3597
|
+
partner: PartnerProfile;
|
|
3598
|
+
/** Initial API key for immediate use */
|
|
3599
|
+
apiKey: PartnerApiKey;
|
|
3600
|
+
}
|
|
3601
|
+
/**
|
|
3602
|
+
* Register a new partner in the marketplace.
|
|
3603
|
+
*
|
|
3604
|
+
* @param registration Partner registration details
|
|
3605
|
+
* @param requestFn HTTP request function
|
|
3606
|
+
* @returns Created partner profile and initial API key
|
|
3607
|
+
*
|
|
3608
|
+
* @example
|
|
3609
|
+
* ```typescript
|
|
3610
|
+
* const result = await registerPartner({
|
|
3611
|
+
* name: 'TechIntegrations Inc',
|
|
3612
|
+
* type: 'integrator',
|
|
3613
|
+
* contactEmail: 'partners@techint.com',
|
|
3614
|
+
* website: 'https://techint.com',
|
|
3615
|
+
* requestedScopes: ['templates:read', 'templates:write', 'analytics:own'],
|
|
3616
|
+
* }, requestFn);
|
|
3617
|
+
* ```
|
|
3618
|
+
*/
|
|
3619
|
+
declare function registerPartner(registration: PartnerRegistration, requestFn: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<PartnerRegistrationResult>;
|
|
3620
|
+
/**
|
|
3621
|
+
* Retrieve partner profile by ID.
|
|
3622
|
+
*
|
|
3623
|
+
* @param partnerId Partner identifier
|
|
3624
|
+
* @param requestFn HTTP request function
|
|
3625
|
+
* @returns Partner profile
|
|
3626
|
+
*
|
|
3627
|
+
* @example
|
|
3628
|
+
* ```typescript
|
|
3629
|
+
* const partner = await getPartner('partner_xyz789', requestFn);
|
|
3630
|
+
* console.log(`Partner: ${partner.name}, Tier: ${partner.tier}`);
|
|
3631
|
+
* ```
|
|
3632
|
+
*/
|
|
3633
|
+
declare function getPartner(partnerId: string, requestFn: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<PartnerProfile>;
|
|
3634
|
+
/**
|
|
3635
|
+
* Update partner profile settings.
|
|
3636
|
+
*
|
|
3637
|
+
* @param partnerId Partner identifier
|
|
3638
|
+
* @param params Update parameters
|
|
3639
|
+
* @param requestFn HTTP request function
|
|
3640
|
+
* @returns Updated partner profile
|
|
3641
|
+
*
|
|
3642
|
+
* @example
|
|
3643
|
+
* ```typescript
|
|
3644
|
+
* const updated = await updatePartner(
|
|
3645
|
+
* 'partner_xyz789',
|
|
3646
|
+
* { tier: 'silver', website: 'https://newsite.com' },
|
|
3647
|
+
* requestFn
|
|
3648
|
+
* );
|
|
3649
|
+
* ```
|
|
3650
|
+
*/
|
|
3651
|
+
declare function updatePartner(partnerId: string, params: UpdatePartnerParams, requestFn: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<PartnerProfile>;
|
|
3652
|
+
/**
|
|
3653
|
+
* Retrieve analytics for a partner in a specific period.
|
|
3654
|
+
*
|
|
3655
|
+
* @param partnerId Partner identifier
|
|
3656
|
+
* @param period ISO month format (e.g., "2026-04")
|
|
3657
|
+
* @param requestFn HTTP request function
|
|
3658
|
+
* @returns Partner analytics data
|
|
3659
|
+
*
|
|
3660
|
+
* @example
|
|
3661
|
+
* ```typescript
|
|
3662
|
+
* const analytics = await getPartnerAnalytics('partner_xyz789', '2026-04', requestFn);
|
|
3663
|
+
* console.log(`Downloads: ${analytics.templateDownloads}`);
|
|
3664
|
+
* console.log(`Revenue: $${(analytics.revenueGenerated / 100).toFixed(2)}`);
|
|
3665
|
+
* ```
|
|
3666
|
+
*/
|
|
3667
|
+
declare function getPartnerAnalytics(partnerId: string, period: string, requestFn: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<PartnerAnalytics>;
|
|
3668
|
+
/**
|
|
3669
|
+
* List all partners with optional filtering.
|
|
3670
|
+
*
|
|
3671
|
+
* @param params Filter parameters
|
|
3672
|
+
* @param requestFn HTTP request function
|
|
3673
|
+
* @returns Array of partner profiles
|
|
3674
|
+
*
|
|
3675
|
+
* @example
|
|
3676
|
+
* ```typescript
|
|
3677
|
+
* const goldPartners = await listPartners({ tier: 'gold', status: 'active' }, requestFn);
|
|
3678
|
+
* ```
|
|
3679
|
+
*/
|
|
3680
|
+
declare function listPartners(params?: {
|
|
3681
|
+
tier?: PartnerTier;
|
|
3682
|
+
status?: PartnerStatus;
|
|
3683
|
+
type?: PartnerType;
|
|
3684
|
+
limit?: number;
|
|
3685
|
+
offset?: number;
|
|
3686
|
+
}, requestFn?: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<PartnerProfile[]>;
|
|
3687
|
+
/**
|
|
3688
|
+
* Generate a scoped API key for partner authentication.
|
|
3689
|
+
*
|
|
3690
|
+
* @param partnerId Partner identifier
|
|
3691
|
+
* @param scopes API scopes to grant
|
|
3692
|
+
* @param expiresAt Optional expiration timestamp
|
|
3693
|
+
* @param requestFn HTTP request function
|
|
3694
|
+
* @returns Generated API key
|
|
3695
|
+
*
|
|
3696
|
+
* @example
|
|
3697
|
+
* ```typescript
|
|
3698
|
+
* const apiKey = await generatePartnerApiKey(
|
|
3699
|
+
* 'partner_xyz789',
|
|
3700
|
+
* ['templates:read', 'verify:white_label'],
|
|
3701
|
+
* undefined,
|
|
3702
|
+
* requestFn
|
|
3703
|
+
* );
|
|
3704
|
+
* console.log(`Use key: ${apiKey.key}`);
|
|
3705
|
+
* ```
|
|
3706
|
+
*/
|
|
3707
|
+
declare function generatePartnerApiKey(partnerId: string, scopes: PartnerScope[], expiresAt?: string, requestFn?: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<PartnerApiKey>;
|
|
3708
|
+
|
|
3709
|
+
/**
|
|
3710
|
+
* Verification template management for the Optropic Marketplace.
|
|
3711
|
+
* Templates are pre-built schemas for specific industries and products.
|
|
3712
|
+
*
|
|
3713
|
+
* @module marketplace/templates
|
|
3714
|
+
*/
|
|
3715
|
+
/**
|
|
3716
|
+
* Industry/product categories for templates.
|
|
3717
|
+
*/
|
|
3718
|
+
type TemplateCategory = 'pharma' | 'automotive' | 'battery' | 'luxury' | 'aerospace' | 'electronics' | 'food' | 'medical_device' | 'defence' | 'general';
|
|
3719
|
+
/**
|
|
3720
|
+
* Template lifecycle status.
|
|
3721
|
+
*/
|
|
3722
|
+
type TemplateStatus = 'draft' | 'in_review' | 'published' | 'deprecated';
|
|
3723
|
+
/**
|
|
3724
|
+
* Field data type constraints.
|
|
3725
|
+
*/
|
|
3726
|
+
type TemplateFieldType = 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'array';
|
|
3727
|
+
/**
|
|
3728
|
+
* Validation rule types.
|
|
3729
|
+
*/
|
|
3730
|
+
type ValidationRuleType = 'required' | 'format' | 'range' | 'dependency' | 'unique';
|
|
3731
|
+
/**
|
|
3732
|
+
* Pricing model for template usage.
|
|
3733
|
+
*/
|
|
3734
|
+
type TemplatePricingModel = 'free' | 'per_verification' | 'monthly' | 'one_time';
|
|
3735
|
+
/**
|
|
3736
|
+
* A field definition in a template schema.
|
|
3737
|
+
*/
|
|
3738
|
+
interface TemplateField {
|
|
3739
|
+
/** Unique field identifier */
|
|
3740
|
+
name: string;
|
|
3741
|
+
/** Data type constraint */
|
|
3742
|
+
type: TemplateFieldType;
|
|
3743
|
+
/** Human-readable label */
|
|
3744
|
+
label: string;
|
|
3745
|
+
/** Detailed field description */
|
|
3746
|
+
description: string;
|
|
3747
|
+
/** Enum values if type is 'enum' */
|
|
3748
|
+
enumValues?: string[];
|
|
3749
|
+
/** Regex pattern for validation */
|
|
3750
|
+
pattern?: string;
|
|
3751
|
+
/** Minimum value (numbers) or length (strings) */
|
|
3752
|
+
min?: number;
|
|
3753
|
+
/** Maximum value (numbers) or length (strings) */
|
|
3754
|
+
max?: number;
|
|
3755
|
+
}
|
|
3756
|
+
/**
|
|
3757
|
+
* A validation rule applied to template fields.
|
|
3758
|
+
*/
|
|
3759
|
+
interface ValidationRule {
|
|
3760
|
+
/** Target field name */
|
|
3761
|
+
field: string;
|
|
3762
|
+
/** Type of validation */
|
|
3763
|
+
rule: ValidationRuleType;
|
|
3764
|
+
/** Rule-specific parameters */
|
|
3765
|
+
params?: Record<string, unknown>;
|
|
3766
|
+
/** Error message if validation fails */
|
|
3767
|
+
message: string;
|
|
3768
|
+
}
|
|
3769
|
+
/**
|
|
3770
|
+
* Complete schema definition for a verification template.
|
|
3771
|
+
*/
|
|
3772
|
+
interface TemplateSchema {
|
|
3773
|
+
/** Schema version identifier */
|
|
3774
|
+
version: '1.0';
|
|
3775
|
+
/** Required fields that must be present */
|
|
3776
|
+
requiredFields: TemplateField[];
|
|
3777
|
+
/** Optional fields that enhance data richness */
|
|
3778
|
+
optionalFields: TemplateField[];
|
|
3779
|
+
/** Validation rules applied to field values */
|
|
3780
|
+
validationRules: ValidationRule[];
|
|
3781
|
+
/** Maps template fields to EU DPP fields (optional) */
|
|
3782
|
+
dppMapping?: Record<string, string>;
|
|
3783
|
+
}
|
|
3784
|
+
/**
|
|
3785
|
+
* Pricing configuration for template usage.
|
|
3786
|
+
*/
|
|
3787
|
+
interface TemplatePricing {
|
|
3788
|
+
/** Pricing model */
|
|
3789
|
+
model: TemplatePricingModel;
|
|
3790
|
+
/** Price in cents (for paid models) */
|
|
3791
|
+
amount?: number;
|
|
3792
|
+
/** Currency code (ISO 4217) */
|
|
3793
|
+
currency?: string;
|
|
3794
|
+
/** Free verification quota for trials */
|
|
3795
|
+
trialVerifications?: number;
|
|
3796
|
+
}
|
|
3797
|
+
/**
|
|
3798
|
+
* Usage statistics for a template.
|
|
3799
|
+
*/
|
|
3800
|
+
interface TemplateStats {
|
|
3801
|
+
/** Total downloads across all users */
|
|
3802
|
+
downloads: number;
|
|
3803
|
+
/** Currently active installations */
|
|
3804
|
+
activeInstallations: number;
|
|
3805
|
+
/** Total verifications performed */
|
|
3806
|
+
totalVerifications: number;
|
|
3807
|
+
/** Average rating (0-5) */
|
|
3808
|
+
averageRating: number;
|
|
3809
|
+
/** Number of reviews received */
|
|
3810
|
+
reviewCount: number;
|
|
3811
|
+
}
|
|
3812
|
+
/**
|
|
3813
|
+
* Author information for templates.
|
|
3814
|
+
*/
|
|
3815
|
+
interface TemplateAuthor {
|
|
3816
|
+
/** Partner ID who created the template */
|
|
3817
|
+
partnerId: string;
|
|
3818
|
+
/** Display name of partner */
|
|
3819
|
+
name: string;
|
|
3820
|
+
}
|
|
3821
|
+
/**
|
|
3822
|
+
* Complete verification template definition.
|
|
3823
|
+
*/
|
|
3824
|
+
interface VerificationTemplate {
|
|
3825
|
+
/** Unique template identifier */
|
|
3826
|
+
id: string;
|
|
3827
|
+
/** Human-readable template name */
|
|
3828
|
+
name: string;
|
|
3829
|
+
/** URL-safe slug for the template */
|
|
3830
|
+
slug: string;
|
|
3831
|
+
/** Semantic version (e.g., "1.0.0") */
|
|
3832
|
+
version: string;
|
|
3833
|
+
/** Industry/product category */
|
|
3834
|
+
category: TemplateCategory;
|
|
3835
|
+
/** Detailed description of the template */
|
|
3836
|
+
description: string;
|
|
3837
|
+
/** Template creator information */
|
|
3838
|
+
author: TemplateAuthor;
|
|
3839
|
+
/** Field and validation schema */
|
|
3840
|
+
schema: TemplateSchema;
|
|
3841
|
+
/** Pricing configuration */
|
|
3842
|
+
pricing: TemplatePricing;
|
|
3843
|
+
/** Usage statistics */
|
|
3844
|
+
stats: TemplateStats;
|
|
3845
|
+
/** Current lifecycle status */
|
|
3846
|
+
status: TemplateStatus;
|
|
3847
|
+
/** Creation timestamp (ISO 8601) */
|
|
3848
|
+
createdAt: string;
|
|
3849
|
+
/** Last update timestamp (ISO 8601) */
|
|
3850
|
+
updatedAt: string;
|
|
3851
|
+
}
|
|
3852
|
+
/**
|
|
3853
|
+
* Request parameters for creating a template.
|
|
3854
|
+
*/
|
|
3855
|
+
interface CreateTemplateParams {
|
|
3856
|
+
/** Template name */
|
|
3857
|
+
name: string;
|
|
3858
|
+
/** Category classification */
|
|
3859
|
+
category: TemplateCategory;
|
|
3860
|
+
/** Detailed description */
|
|
3861
|
+
description: string;
|
|
3862
|
+
/** Field and validation schema */
|
|
3863
|
+
schema: TemplateSchema;
|
|
3864
|
+
/** Pricing configuration */
|
|
3865
|
+
pricing: TemplatePricing;
|
|
3866
|
+
/** Optional DPP field mappings */
|
|
3867
|
+
dppMapping?: Record<string, string>;
|
|
3868
|
+
}
|
|
3869
|
+
/**
|
|
3870
|
+
* Request parameters for updating a template.
|
|
3871
|
+
*/
|
|
3872
|
+
interface UpdateTemplateParams {
|
|
3873
|
+
/** Updated name */
|
|
3874
|
+
name?: string;
|
|
3875
|
+
/** Updated description */
|
|
3876
|
+
description?: string;
|
|
3877
|
+
/** Updated schema */
|
|
3878
|
+
schema?: TemplateSchema;
|
|
3879
|
+
/** Updated pricing */
|
|
3880
|
+
pricing?: TemplatePricing;
|
|
3881
|
+
/** Updated DPP mappings */
|
|
3882
|
+
dppMapping?: Record<string, string>;
|
|
3883
|
+
}
|
|
3884
|
+
/**
|
|
3885
|
+
* Template publication request.
|
|
3886
|
+
*/
|
|
3887
|
+
interface PublishTemplateParams {
|
|
3888
|
+
/** Changelog entry for this version */
|
|
3889
|
+
changelog?: string;
|
|
3890
|
+
/** Major/minor version bump flag */
|
|
3891
|
+
bumpVersion?: 'major' | 'minor' | 'patch';
|
|
3892
|
+
}
|
|
3893
|
+
/**
|
|
3894
|
+
* Template deprecation request.
|
|
3895
|
+
*/
|
|
3896
|
+
interface DeprecateTemplateParams {
|
|
3897
|
+
/** Reason for deprecation */
|
|
3898
|
+
reason: string;
|
|
3899
|
+
/** Recommended replacement template ID */
|
|
3900
|
+
replacementId?: string;
|
|
3901
|
+
/** Grace period in days before removal */
|
|
3902
|
+
gracePeriodDays?: number;
|
|
3903
|
+
}
|
|
3904
|
+
/**
|
|
3905
|
+
* Template rating submission.
|
|
3906
|
+
*/
|
|
3907
|
+
interface RateTemplateParams {
|
|
3908
|
+
/** Rating from 1-5 stars */
|
|
3909
|
+
rating: number;
|
|
3910
|
+
/** Optional review text */
|
|
3911
|
+
review?: string;
|
|
3912
|
+
}
|
|
3913
|
+
/**
|
|
3914
|
+
* Validation result from schema conformance check.
|
|
3915
|
+
*/
|
|
3916
|
+
interface ValidationResult {
|
|
3917
|
+
/** Whether validation passed */
|
|
3918
|
+
valid: boolean;
|
|
3919
|
+
/** Validation errors if any */
|
|
3920
|
+
errors?: Array<{
|
|
3921
|
+
field: string;
|
|
3922
|
+
message: string;
|
|
3923
|
+
}>;
|
|
3924
|
+
}
|
|
3925
|
+
/**
|
|
3926
|
+
* Response from template search/list operations.
|
|
3927
|
+
*/
|
|
3928
|
+
interface ListTemplatesResponse {
|
|
3929
|
+
/** Array of templates */
|
|
3930
|
+
templates: VerificationTemplate[];
|
|
3931
|
+
/** Total count matching filter */
|
|
3932
|
+
total: number;
|
|
3933
|
+
/** Current offset */
|
|
3934
|
+
offset: number;
|
|
3935
|
+
/** Current limit */
|
|
3936
|
+
limit: number;
|
|
3937
|
+
}
|
|
3938
|
+
/**
|
|
3939
|
+
* Create a new verification template.
|
|
3940
|
+
*
|
|
3941
|
+
* @param partnerId Partner creating the template
|
|
3942
|
+
* @param params Template creation parameters
|
|
3943
|
+
* @param requestFn HTTP request function
|
|
3944
|
+
* @returns Created template (initially in draft status)
|
|
3945
|
+
*
|
|
3946
|
+
* @example
|
|
3947
|
+
* ```typescript
|
|
3948
|
+
* const template = await createTemplate(
|
|
3949
|
+
* 'partner_xyz789',
|
|
3950
|
+
* {
|
|
3951
|
+
* name: 'Pharma Serialization',
|
|
3952
|
+
* category: 'pharma',
|
|
3953
|
+
* description: 'EU Pharma Serialization Template',
|
|
3954
|
+
* schema: {...schemaObject},
|
|
3955
|
+
* pricing: { model: 'per_verification', amount: 50 },
|
|
3956
|
+
* },
|
|
3957
|
+
* requestFn
|
|
3958
|
+
* );
|
|
3959
|
+
* ```
|
|
3960
|
+
*/
|
|
3961
|
+
declare function createTemplate(partnerId: string, params: CreateTemplateParams, requestFn: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<VerificationTemplate>;
|
|
3962
|
+
/**
|
|
3963
|
+
* Retrieve a template by ID.
|
|
3964
|
+
*
|
|
3965
|
+
* @param templateId Template identifier
|
|
3966
|
+
* @param requestFn HTTP request function
|
|
3967
|
+
* @returns Template definition
|
|
3968
|
+
*
|
|
3969
|
+
* @example
|
|
3970
|
+
* ```typescript
|
|
3971
|
+
* const template = await getTemplate('tmpl_pharma_001', requestFn);
|
|
3972
|
+
* ```
|
|
3973
|
+
*/
|
|
3974
|
+
declare function getTemplate(templateId: string, requestFn: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<VerificationTemplate>;
|
|
3975
|
+
/**
|
|
3976
|
+
* Update a template (draft or published with minor changes).
|
|
3977
|
+
*
|
|
3978
|
+
* @param templateId Template identifier
|
|
3979
|
+
* @param params Update parameters
|
|
3980
|
+
* @param requestFn HTTP request function
|
|
3981
|
+
* @returns Updated template
|
|
3982
|
+
*
|
|
3983
|
+
* @example
|
|
3984
|
+
* ```typescript
|
|
3985
|
+
* const updated = await updateTemplate(
|
|
3986
|
+
* 'tmpl_pharma_001',
|
|
3987
|
+
* { description: 'Updated description' },
|
|
3988
|
+
* requestFn
|
|
3989
|
+
* );
|
|
3990
|
+
* ```
|
|
3991
|
+
*/
|
|
3992
|
+
declare function updateTemplate(templateId: string, params: UpdateTemplateParams, requestFn: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<VerificationTemplate>;
|
|
3993
|
+
/**
|
|
3994
|
+
* Publish a template to the marketplace (moves from draft → published).
|
|
3995
|
+
*
|
|
3996
|
+
* @param templateId Template identifier
|
|
3997
|
+
* @param params Publication parameters
|
|
3998
|
+
* @param requestFn HTTP request function
|
|
3999
|
+
* @returns Published template
|
|
4000
|
+
*
|
|
4001
|
+
* @example
|
|
4002
|
+
* ```typescript
|
|
4003
|
+
* const published = await publishTemplate(
|
|
4004
|
+
* 'tmpl_pharma_001',
|
|
4005
|
+
* { changelog: 'Initial release' },
|
|
4006
|
+
* requestFn
|
|
4007
|
+
* );
|
|
4008
|
+
* ```
|
|
4009
|
+
*/
|
|
4010
|
+
declare function publishTemplate(templateId: string, params?: PublishTemplateParams, requestFn?: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<VerificationTemplate>;
|
|
4011
|
+
/**
|
|
4012
|
+
* Deprecate a template (no longer recommended for new use).
|
|
4013
|
+
*
|
|
4014
|
+
* @param templateId Template identifier
|
|
4015
|
+
* @param params Deprecation parameters
|
|
4016
|
+
* @param requestFn HTTP request function
|
|
4017
|
+
* @returns Deprecated template
|
|
4018
|
+
*
|
|
4019
|
+
* @example
|
|
4020
|
+
* ```typescript
|
|
4021
|
+
* const deprecated = await deprecateTemplate(
|
|
4022
|
+
* 'tmpl_pharma_old',
|
|
4023
|
+
* {
|
|
4024
|
+
* reason: 'Superseded by v2.0 with EU DPP compliance',
|
|
4025
|
+
* replacementId: 'tmpl_pharma_002',
|
|
4026
|
+
* },
|
|
4027
|
+
* requestFn
|
|
4028
|
+
* );
|
|
4029
|
+
* ```
|
|
4030
|
+
*/
|
|
4031
|
+
declare function deprecateTemplate(templateId: string, params: DeprecateTemplateParams, requestFn?: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<VerificationTemplate>;
|
|
4032
|
+
/**
|
|
4033
|
+
* List templates with filtering and pagination.
|
|
4034
|
+
*
|
|
4035
|
+
* @param params Filter and pagination parameters
|
|
4036
|
+
* @param requestFn HTTP request function
|
|
4037
|
+
* @returns Paginated template list
|
|
4038
|
+
*
|
|
4039
|
+
* @example
|
|
4040
|
+
* ```typescript
|
|
4041
|
+
* const result = await listTemplates(
|
|
4042
|
+
* { category: 'battery', status: 'published', limit: 20 },
|
|
4043
|
+
* requestFn
|
|
4044
|
+
* );
|
|
4045
|
+
* ```
|
|
4046
|
+
*/
|
|
4047
|
+
declare function listTemplates(params?: {
|
|
4048
|
+
category?: TemplateCategory;
|
|
4049
|
+
status?: TemplateStatus;
|
|
4050
|
+
author?: string;
|
|
4051
|
+
limit?: number;
|
|
4052
|
+
offset?: number;
|
|
4053
|
+
}, requestFn?: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<ListTemplatesResponse>;
|
|
4054
|
+
/**
|
|
4055
|
+
* Search templates by keyword.
|
|
4056
|
+
*
|
|
4057
|
+
* @param query Search query string
|
|
4058
|
+
* @param params Optional filter parameters
|
|
4059
|
+
* @param requestFn HTTP request function
|
|
4060
|
+
* @returns Search results
|
|
4061
|
+
*
|
|
4062
|
+
* @example
|
|
4063
|
+
* ```typescript
|
|
4064
|
+
* const results = await searchTemplates('battery passport', { limit: 10 }, requestFn);
|
|
4065
|
+
* ```
|
|
4066
|
+
*/
|
|
4067
|
+
declare function searchTemplates(query: string, params?: {
|
|
4068
|
+
category?: TemplateCategory;
|
|
4069
|
+
limit?: number;
|
|
4070
|
+
}, requestFn?: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<ListTemplatesResponse>;
|
|
4071
|
+
/**
|
|
4072
|
+
* Install/activate a template in a tenant's account.
|
|
4073
|
+
*
|
|
4074
|
+
* @param templateId Template identifier
|
|
4075
|
+
* @param requestFn HTTP request function
|
|
4076
|
+
* @returns Installed template reference
|
|
4077
|
+
*
|
|
4078
|
+
* @example
|
|
4079
|
+
* ```typescript
|
|
4080
|
+
* await installTemplate('tmpl_pharma_001', requestFn);
|
|
4081
|
+
* ```
|
|
4082
|
+
*/
|
|
4083
|
+
declare function installTemplate(templateId: string, requestFn?: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<VerificationTemplate>;
|
|
4084
|
+
/**
|
|
4085
|
+
* Uninstall/deactivate a template from a tenant's account.
|
|
4086
|
+
*
|
|
4087
|
+
* @param templateId Template identifier
|
|
4088
|
+
* @param requestFn HTTP request function
|
|
4089
|
+
* @returns Uninstalled template reference
|
|
4090
|
+
*
|
|
4091
|
+
* @example
|
|
4092
|
+
* ```typescript
|
|
4093
|
+
* await uninstallTemplate('tmpl_pharma_001', requestFn);
|
|
4094
|
+
* ```
|
|
4095
|
+
*/
|
|
4096
|
+
declare function uninstallTemplate(templateId: string, requestFn?: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<VerificationTemplate>;
|
|
4097
|
+
/**
|
|
4098
|
+
* Rate and review a template.
|
|
4099
|
+
*
|
|
4100
|
+
* @param templateId Template identifier
|
|
4101
|
+
* @param params Rating and review parameters
|
|
4102
|
+
* @param requestFn HTTP request function
|
|
4103
|
+
* @returns Updated template stats
|
|
4104
|
+
*
|
|
4105
|
+
* @example
|
|
4106
|
+
* ```typescript
|
|
4107
|
+
* await rateTemplate(
|
|
4108
|
+
* 'tmpl_pharma_001',
|
|
4109
|
+
* { rating: 5, review: 'Excellent template, saved us months of work' },
|
|
4110
|
+
* requestFn
|
|
4111
|
+
* );
|
|
4112
|
+
* ```
|
|
4113
|
+
*/
|
|
4114
|
+
declare function rateTemplate(templateId: string, params: RateTemplateParams, requestFn?: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<TemplateStats>;
|
|
4115
|
+
/**
|
|
4116
|
+
* Validate data against a template schema.
|
|
4117
|
+
*
|
|
4118
|
+
* @param templateId Template identifier
|
|
4119
|
+
* @param data Data to validate
|
|
4120
|
+
* @param requestFn HTTP request function
|
|
4121
|
+
* @returns Validation result with errors if any
|
|
4122
|
+
*
|
|
4123
|
+
* @example
|
|
4124
|
+
* ```typescript
|
|
4125
|
+
* const result = await validateAgainstTemplate(
|
|
4126
|
+
* 'tmpl_pharma_001',
|
|
4127
|
+
* { ndc: '0069-1234-56', lotNumber: 'ABC123' },
|
|
4128
|
+
* requestFn
|
|
4129
|
+
* );
|
|
4130
|
+
* if (!result.valid) {
|
|
4131
|
+
* console.log('Validation errors:', result.errors);
|
|
4132
|
+
* }
|
|
4133
|
+
* ```
|
|
4134
|
+
*/
|
|
4135
|
+
declare function validateAgainstTemplate(templateId: string, data: unknown, requestFn?: (method: string, path: string, body?: unknown) => Promise<unknown>): Promise<ValidationResult>;
|
|
4136
|
+
|
|
4137
|
+
declare const SDK_VERSION = "3.0.0";
|
|
1328
4138
|
|
|
1329
|
-
export { type ApiKey, type Asset, AssetsResource, type AuditEvent, AuditResource, AuthenticationError, type BatchCreateParams, type BatchCreateResult, BatchNotFoundError, type BatteryPassportData, type ChainVerifyResult, CodeNotFoundError, type ComplianceConfig, ComplianceResource, type ConformityDeclaration, type CreateAssetParams, type CreateAuditEventParams, type CreateKeyParams, type CreateKeyResult, type CreateKeysetParams, type CreateSchemaParams, type DPPCategory, type DPPMetadata, type Document, type DocumentVerifyResult, DocumentsResource, type EnrollDocumentParams, type ErrorCode, type ExportParams, type ExportResult, type FiberEntry, type FilterHeader, type FilterSyncResult, InvalidCodeError, InvalidGTINError, InvalidSerialError, KeysResource, type Keyset, KeysetsResource, type ListAssetsParams, type ListAssetsResponse, type ListAuditParams, type ListAuditResponse, type ListDocumentsParams, type ListDocumentsResponse, type ListKeysetsParams, type ListKeysetsResponse, type ListProvenanceParams, type ListProvenanceResponse, type ListSchemasParams, type ListSchemasResponse, type MerkleProof, type MerkleRoot, NetworkError, type OfflineVerifyOptions, type OfflineVerifyResult, OptropicClient, type OptropicConfig, OptropicError, type ProvenanceChain, type ProvenanceEvent, type ProvenanceEventType, type ProvenanceLocation, ProvenanceResource, QuotaExceededError, RateLimitedError, type RecordProvenanceParams, type RequestFn, type RetryConfig, RevokedCodeError, SDK_VERSION, type SchemaValidationResult, SchemasResource, ServiceUnavailableError, StaleFilterError, type SubstanceEntry, type TextilePassportData, TimeoutError, type UpdateSchemaParams, type VerifyDocumentParams, type VerifyProvenanceResult, type VerifyResult, type VerticalSchema, type WebhookVerifyOptions, type WebhookVerifyResult, buildDPPConfig, createClient, createErrorFromResponse, parseFilterHeader, parseSaltsHeader, validateDPPMetadata, verifyOffline, verifyWebhookSignature };
|
|
4139
|
+
export { type ApiKey, type Asset, AssetsResource, type AuditChain, type AuditEvent, type AuditRecord, type AuditRecordType, AuditResource, AuthenticationError, type BatchCreateParams, type BatchCreateResult, type BatchJob, BatchNotFoundError, type BatchResult, type BatchRevokeResult, type BatchVerifyResult, BatchesResource, type BatteryPassportData, type CaptureConditions, type ChainVerifyResult, CodeNotFoundError, type ComplianceConfig, ComplianceResource, type ConditionStatus, type ConformityDeclaration, type ConsensusConfig, type ConsensusResult, type ConsensusResultPayload, type CreateAssetParams, type CreateAuditEventParams, type CreateBatchParams, type CreateKeyParams, type CreateKeyResult, type CreateKeysetParams, type CreateOrganizationParams, type CreateRLSPolicyParams, type CreateSchemaParams, type CreateTemplateParams, type DPPAccessContext, DPPAccessLevel, type DPPAccessPolicy, type DPPCategory, type DPPFieldVisibility, type DPPMetadata, type DataResidency, type DefenceMetadata, type DeprecateTemplateParams, type DescriptorExchangePayload, type DimensionMatch, type Document, type DocumentVerifyResult, DocumentsResource, type EPCISBizStep, type EPCISDisposition, type EPCISEvent, type EPCISEventDocument, type EPCISEventType, type EPCISMapping, type EndpointUsage, type EnrollDocumentParams, type ErrorCode, type ErrorPayload, type ExportParams, type ExportResult, type FiberEntry, type FilterHeader, type FilterSyncResult, type GS1ApplicationIdentifier, type GS1BuilderInput, type GS1ParsedComponent, type GS1ParsedURI, type GTINValidationResult, type GetUsageBreakdownParams, type GetUsageParams, type HandlingCaveat, type HandshakeAcceptPayload, type HandshakeInitPayload, type HazardousSubstanceEntry, type InitiateChallengeParams, InvalidCodeError, InvalidGTINError, InvalidSerialError, type InviteMemberParams, type InviteStatus, type KeyInfo, KeysResource, type Keyset, KeysetsResource, type ListAssetsParams, type ListAssetsResponse, type ListAuditParams, type ListAuditResponse, type ListBatchesParams, type ListDocumentsParams, type ListDocumentsResponse, type ListKeysetsParams, type ListKeysetsResponse, type ListProvenanceParams, type ListProvenanceResponse, type ListSchemasParams, type ListSchemasResponse, type ListTemplatesResponse, type LogisticsMovement, type LogisticsMovementType, type M2MChallenge, type M2MDevice, M2MResource, type M2MVerifyRequest, type M2MVerifyResult, type MemberStatus, type MerkleProof, type MerkleRoot, type NATOUIDData, NetworkError, type OfflineVerifyOptions, type OfflineVerifyResult, type OptropicAssetLookup, OptropicClient, type OptropicConfig, OptropicError, type OrgPlanTier, type OrgStatus, type Organization, type OrganizationSettings, type P2PMessage, type PartnerAnalytics, type PartnerApiKey, type PartnerProfile, type PartnerRegistration, type PartnerRegistrationResult, type PartnerScope, type PartnerStatus, type PartnerTier, type PartnerType, Permission, type PermissionValue, type PhysicalDescriptor, type PriorityDesignator, type ProvenanceChain, type ProvenanceEvent, type ProvenanceEventType, type ProvenanceLocation, ProvenanceResource, type PublishTemplateParams, type QRCodePayload, QuotaExceededError, type QuotaInfo, type RLSAction, type RLSCondition, type RLSOperator, type RLSPolicy, type RLSResourceType, type RateLimitInfo, RateLimitedError, type RateTemplateParams, type ReadinessScore, type ReadinessThresholds, type RecordProvenanceParams, type RegisterDeviceParams, type RequestFn, type RetryConfig, RevokedCodeError, type RotateKeyParams, type RotateKeyResult, SDK_VERSION, type SchemaValidationResult, SchemasResource, ServiceUnavailableError, type ShelfLife, StaleFilterError, type StanagClassification, type SubstanceEntry, type SupplyClass, type TemplateAuthor, type TemplateCategory, type TemplateField, type TemplateFieldType, type TemplatePricing, type TemplatePricingModel, type TemplateSchema, type TemplateStats, type TemplateStatus, type ValidationResult as TemplateValidationResult, type Tenant, type TenantInvite, type TenantLimits, type TenantMember, type TenantRole, type TenantUsageQuota, TenantsResource, type TextilePassportData, TimeoutError, type ToEPCISEventOptions, type UIDBatch, type UIDEncoding, type UpdateOrganizationParams, type UpdatePartnerParams, type UpdateSchemaParams, type UpdateTemplateParams, type UpdateUsageQuotaParams, type UsageReport, type ValidationResult$1 as ValidationResult, type ValidationRule, type ValidationRuleType, type VerificationTemplate, type VerifyDocumentParams, type VerifyProvenanceResult, type VerifyResult, type VerticalSchema, type WaitOptions, type WebhookVerifyOptions, type WebhookVerifyResult, appendRecord, buildBatteryPassportQR, buildDPPConfig, buildDefenceMetadata, buildEPCISDocument, buildGS1DigitalLink, calculateReadiness, calibrateThreshold, computeDistance, computeSimilarity, createAuditChain, createClient, createConsensusResultMessage, createDescriptorExchange, createErrorFromResponse, createHandshakeAccept, createHandshakeInit, createOrganization, createRLSPolicy, createTemplate, decodeNATOUID, deleteRLSPolicy, deprecateTemplate, deserializeMessage, encodeNATOUID, evaluateConsensus, exportChain, filterDPPByAccess, generatePartnerApiKey, generateQRCodePayload, getAILabel, getDPPAccessPolicy, getEPCISMappingTable, getOrganization, getPartner, getPartnerAnalytics, getRolePermissions, getSupportedAIs, getTemplate, getUsageQuota, importChain, installTemplate, inviteMember, isValidAI, listMembers, listPartners, listRLSPolicies, listTemplates, mapMovementToProvenance, mapNATOUIDToOptropic, mapOptropicToNATOUID, mapToEPCIS, mapToOptropicAsset, parseFilterHeader, parseGS1DigitalLink, parseSaltsHeader, provenanceChainToEPCIS, publishTemplate, rateTemplate, registerPartner, removeMember, searchTemplates, serializeMessage, toEPCISEvent, uninstallTemplate, updateMemberRole, updateOrganization, updatePartner, updateTemplate, updateUsageQuota, validateAgainstTemplate, validateBatteryPassport, validateDPPMetadata, validateDefenceMetadata, validateGTIN, validateLogisticsMovement, validateMessage, validateNATOUID, verifyChain, verifyOffline, verifyWebhookSignature };
|