@plasius/economy 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -39,6 +39,52 @@ declare function parseIsoTimestamp(value: IsoTimestamp): number;
 /** Returns a new record with keys sorted for canonical serialization. */
 declare function sortStringRecord(value: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
 
+type TokenSource = "shopify" | "ayet" | "bitlabs" | "subscription" | "event" | "competition" | "adjustment";
+type LotTransferPolicy = "household-allocatable" | "same-user-only" | "non-transferable";
+type LotRefundState = "none" | "partial" | "refunded" | "disputed" | "chargeback-lost";
+interface SourceLotV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly lotId: LotId;
+    readonly walletId: WalletId;
+    readonly beneficiaryAccountId: AccountId;
+    readonly householdId?: HouseholdId;
+    readonly payerAccountId?: AccountId;
+    readonly source: TokenSource;
+    readonly providerEventId?: ProviderEventId;
+    readonly rateVersion: string;
+    readonly settlementEvidenceHash: string;
+    readonly transferPolicy: LotTransferPolicy;
+    readonly refundState: LotRefundState;
+    readonly originalAmount: TokenSubunitString;
+    readonly remainingAmount: TokenSubunitString;
+    readonly heldAmount: TokenSubunitString;
+    readonly reversedAmount: TokenSubunitString;
+    readonly settledAt: IsoTimestamp;
+    readonly creditedAt: IsoTimestamp;
+    readonly cohortKey?: string;
+}
+type LotUseOperation = "allocate" | "spend" | "reclaim" | "refund";
+interface LotUseContextV1 {
+    readonly operation: LotUseOperation;
+    readonly beneficiaryAccountId: AccountId;
+    readonly householdId?: HouseholdId;
+}
+interface SourceLotSliceV1 {
+    readonly lotId: LotId;
+    readonly amount: TokenSubunitString;
+}
+/** Validates source-lot arithmetic, evidence, and immutable provenance fields. */
+declare function assertSourceLot(lot: SourceLotV1): void;
+/** Returns unheld, unconsumed TokenSubunits in a source lot. */
+declare function availableSourceLotAmount(lot: SourceLotV1): bigint;
+/** Evaluates provider/source restrictions without trusting a browser claim. */
+declare function canUseSourceLot(lot: SourceLotV1, context: LotUseContextV1): boolean;
+/**
+ * Selects eligible lots deterministically in credited-time/lot-id order.
+ * The returned slices are a proposal; persistence must consume them atomically.
+ */
+declare function selectSourceLots(lots: readonly SourceLotV1[], requestedAmount: TokenSubunitString, context: LotUseContextV1): readonly SourceLotSliceV1[];
+
 type ActivityType = "purchase" | "subscription" | "rewarded-ad" | "offerwall" | "allocation" | "boost" | "reclaim" | "spend" | "hold" | "refund" | "chargeback" | "adjustment" | "reversal" | "event" | "competition";
 type ActivityStatus = "pending" | "held" | "settled" | "reversed" | "failed";
 /** One signed side of an immutable double-entry transaction. */
@@ -75,6 +121,8 @@ interface ActivityEntryV1 {
     readonly status: ActivityStatus;
     readonly occurredAt: IsoTimestamp;
     readonly amount: TokenSubunitString;
+    /** Stable source identity used for filtering and provenance presentation. */
+    readonly source: TokenSource;
     readonly beneficiaryAccountId?: AccountId;
     readonly maskedReference?: string;
     readonly sourceLabel: string;
@@ -217,52 +265,6 @@ declare function convertRewardPayout(providerPayoutMinorUnits: string, rate: Rew
 /** Maps BitLabs' signed callback state into an immutable journal transition. */
 declare function mapBitLabsConversionState(state: string): RewardActivityTransitionV1;
 
-type TokenSource = "shopify" | "ayet" | "bitlabs" | "subscription" | "event" | "competition" | "adjustment";
-type LotTransferPolicy = "household-allocatable" | "same-user-only" | "non-transferable";
-type LotRefundState = "none" | "partial" | "refunded" | "disputed" | "chargeback-lost";
-interface SourceLotV1 {
-    readonly schemaVersion: EconomyContractVersion;
-    readonly lotId: LotId;
-    readonly walletId: WalletId;
-    readonly beneficiaryAccountId: AccountId;
-    readonly householdId?: HouseholdId;
-    readonly payerAccountId?: AccountId;
-    readonly source: TokenSource;
-    readonly providerEventId?: ProviderEventId;
-    readonly rateVersion: string;
-    readonly settlementEvidenceHash: string;
-    readonly transferPolicy: LotTransferPolicy;
-    readonly refundState: LotRefundState;
-    readonly originalAmount: TokenSubunitString;
-    readonly remainingAmount: TokenSubunitString;
-    readonly heldAmount: TokenSubunitString;
-    readonly reversedAmount: TokenSubunitString;
-    readonly settledAt: IsoTimestamp;
-    readonly creditedAt: IsoTimestamp;
-    readonly cohortKey?: string;
-}
-type LotUseOperation = "allocate" | "spend" | "reclaim" | "refund";
-interface LotUseContextV1 {
-    readonly operation: LotUseOperation;
-    readonly beneficiaryAccountId: AccountId;
-    readonly householdId?: HouseholdId;
-}
-interface SourceLotSliceV1 {
-    readonly lotId: LotId;
-    readonly amount: TokenSubunitString;
-}
-/** Validates source-lot arithmetic, evidence, and immutable provenance fields. */
-declare function assertSourceLot(lot: SourceLotV1): void;
-/** Returns unheld, unconsumed TokenSubunits in a source lot. */
-declare function availableSourceLotAmount(lot: SourceLotV1): bigint;
-/** Evaluates provider/source restrictions without trusting a browser claim. */
-declare function canUseSourceLot(lot: SourceLotV1, context: LotUseContextV1): boolean;
-/**
- * Selects eligible lots deterministically in credited-time/lot-id order.
- * The returned slices are a proposal; persistence must consume them atomically.
- */
-declare function selectSourceLots(lots: readonly SourceLotV1[], requestedAmount: TokenSubunitString, context: LotUseContextV1): readonly SourceLotSliceV1[];
-
 type AllocationStatus = "active" | "closed";
 type PeriodicLimitWindow = "daily" | "weekly" | "monthly";
 interface GameplayLimitsV1 {

package/dist/index.d.ts

@@ -39,6 +39,52 @@ declare function parseIsoTimestamp(value: IsoTimestamp): number;
 /** Returns a new record with keys sorted for canonical serialization. */
 declare function sortStringRecord(value: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
 
+type TokenSource = "shopify" | "ayet" | "bitlabs" | "subscription" | "event" | "competition" | "adjustment";
+type LotTransferPolicy = "household-allocatable" | "same-user-only" | "non-transferable";
+type LotRefundState = "none" | "partial" | "refunded" | "disputed" | "chargeback-lost";
+interface SourceLotV1 {
+    readonly schemaVersion: EconomyContractVersion;
+    readonly lotId: LotId;
+    readonly walletId: WalletId;
+    readonly beneficiaryAccountId: AccountId;
+    readonly householdId?: HouseholdId;
+    readonly payerAccountId?: AccountId;
+    readonly source: TokenSource;
+    readonly providerEventId?: ProviderEventId;
+    readonly rateVersion: string;
+    readonly settlementEvidenceHash: string;
+    readonly transferPolicy: LotTransferPolicy;
+    readonly refundState: LotRefundState;
+    readonly originalAmount: TokenSubunitString;
+    readonly remainingAmount: TokenSubunitString;
+    readonly heldAmount: TokenSubunitString;
+    readonly reversedAmount: TokenSubunitString;
+    readonly settledAt: IsoTimestamp;
+    readonly creditedAt: IsoTimestamp;
+    readonly cohortKey?: string;
+}
+type LotUseOperation = "allocate" | "spend" | "reclaim" | "refund";
+interface LotUseContextV1 {
+    readonly operation: LotUseOperation;
+    readonly beneficiaryAccountId: AccountId;
+    readonly householdId?: HouseholdId;
+}
+interface SourceLotSliceV1 {
+    readonly lotId: LotId;
+    readonly amount: TokenSubunitString;
+}
+/** Validates source-lot arithmetic, evidence, and immutable provenance fields. */
+declare function assertSourceLot(lot: SourceLotV1): void;
+/** Returns unheld, unconsumed TokenSubunits in a source lot. */
+declare function availableSourceLotAmount(lot: SourceLotV1): bigint;
+/** Evaluates provider/source restrictions without trusting a browser claim. */
+declare function canUseSourceLot(lot: SourceLotV1, context: LotUseContextV1): boolean;
+/**
+ * Selects eligible lots deterministically in credited-time/lot-id order.
+ * The returned slices are a proposal; persistence must consume them atomically.
+ */
+declare function selectSourceLots(lots: readonly SourceLotV1[], requestedAmount: TokenSubunitString, context: LotUseContextV1): readonly SourceLotSliceV1[];
+
 type ActivityType = "purchase" | "subscription" | "rewarded-ad" | "offerwall" | "allocation" | "boost" | "reclaim" | "spend" | "hold" | "refund" | "chargeback" | "adjustment" | "reversal" | "event" | "competition";
 type ActivityStatus = "pending" | "held" | "settled" | "reversed" | "failed";
 /** One signed side of an immutable double-entry transaction. */
@@ -75,6 +121,8 @@ interface ActivityEntryV1 {
     readonly status: ActivityStatus;
     readonly occurredAt: IsoTimestamp;
     readonly amount: TokenSubunitString;
+    /** Stable source identity used for filtering and provenance presentation. */
+    readonly source: TokenSource;
     readonly beneficiaryAccountId?: AccountId;
     readonly maskedReference?: string;
     readonly sourceLabel: string;
@@ -217,52 +265,6 @@ declare function convertRewardPayout(providerPayoutMinorUnits: string, rate: Rew
 /** Maps BitLabs' signed callback state into an immutable journal transition. */
 declare function mapBitLabsConversionState(state: string): RewardActivityTransitionV1;
 
-type TokenSource = "shopify" | "ayet" | "bitlabs" | "subscription" | "event" | "competition" | "adjustment";
-type LotTransferPolicy = "household-allocatable" | "same-user-only" | "non-transferable";
-type LotRefundState = "none" | "partial" | "refunded" | "disputed" | "chargeback-lost";
-interface SourceLotV1 {
-    readonly schemaVersion: EconomyContractVersion;
-    readonly lotId: LotId;
-    readonly walletId: WalletId;
-    readonly beneficiaryAccountId: AccountId;
-    readonly householdId?: HouseholdId;
-    readonly payerAccountId?: AccountId;
-    readonly source: TokenSource;
-    readonly providerEventId?: ProviderEventId;
-    readonly rateVersion: string;
-    readonly settlementEvidenceHash: string;
-    readonly transferPolicy: LotTransferPolicy;
-    readonly refundState: LotRefundState;
-    readonly originalAmount: TokenSubunitString;
-    readonly remainingAmount: TokenSubunitString;
-    readonly heldAmount: TokenSubunitString;
-    readonly reversedAmount: TokenSubunitString;
-    readonly settledAt: IsoTimestamp;
-    readonly creditedAt: IsoTimestamp;
-    readonly cohortKey?: string;
-}
-type LotUseOperation = "allocate" | "spend" | "reclaim" | "refund";
-interface LotUseContextV1 {
-    readonly operation: LotUseOperation;
-    readonly beneficiaryAccountId: AccountId;
-    readonly householdId?: HouseholdId;
-}
-interface SourceLotSliceV1 {
-    readonly lotId: LotId;
-    readonly amount: TokenSubunitString;
-}
-/** Validates source-lot arithmetic, evidence, and immutable provenance fields. */
-declare function assertSourceLot(lot: SourceLotV1): void;
-/** Returns unheld, unconsumed TokenSubunits in a source lot. */
-declare function availableSourceLotAmount(lot: SourceLotV1): bigint;
-/** Evaluates provider/source restrictions without trusting a browser claim. */
-declare function canUseSourceLot(lot: SourceLotV1, context: LotUseContextV1): boolean;
-/**
- * Selects eligible lots deterministically in credited-time/lot-id order.
- * The returned slices are a proposal; persistence must consume them atomically.
- */
-declare function selectSourceLots(lots: readonly SourceLotV1[], requestedAmount: TokenSubunitString, context: LotUseContextV1): readonly SourceLotSliceV1[];
-
 type AllocationStatus = "active" | "closed";
 type PeriodicLimitWindow = "daily" | "weekly" | "monthly";
 interface GameplayLimitsV1 {

package/dist/index.js

@@ -37,7 +37,7 @@ function assertInRange(amount) {
 }
 function parseTokenSubunits(value) {
   economyAssert(
-    CANONICAL_INTEGER.test(value),
+    typeof value === "string" && CANONICAL_INTEGER.test(value),
     "INVALID_AMOUNT",
     "TokenSubunit amount must be a canonical base-10 integer string"
   );
@@ -86,12 +86,17 @@ var ECONOMY_CONTRACT_VERSION = "1";
 var IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
 function assertEconomyIdentifier(value, label = "identifier") {
   economyAssert(
-    IDENTIFIER.test(value),
+    typeof value === "string" && IDENTIFIER.test(value),
     "INVALID_CONTRACT",
     `${label} must be a non-empty opaque identifier`
   );
 }
 function parseIsoTimestamp(value) {
+  economyAssert(
+    typeof value === "string",
+    "INVALID_CONTRACT",
+    "Timestamp must be an ISO-8601 UTC value"
+  );
   const match = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{3}))?Z$/u.exec(
     value
   );
@@ -813,6 +818,15 @@ var ACTIVITY_STATUSES = /* @__PURE__ */ new Set([
   "reversed",
   "failed"
 ]);
+var ACTIVITY_SOURCES = /* @__PURE__ */ new Set([
+  "shopify",
+  "ayet",
+  "bitlabs",
+  "subscription",
+  "event",
+  "competition",
+  "adjustment"
+]);
 function assertCanonicalHash(value, label) {
   economyAssert(
     /^sha256:[a-f0-9]{64}$/u.test(value),
@@ -834,9 +848,9 @@ function assertActivityEntry(entry) {
   );
   assertEconomyIdentifier(entry.transactionId, "transactionId");
   economyAssert(
-    ACTIVITY_TYPES.has(entry.activityType) && ACTIVITY_STATUSES.has(entry.status),
+    ACTIVITY_TYPES.has(entry.activityType) && ACTIVITY_STATUSES.has(entry.status) && ACTIVITY_SOURCES.has(entry.source),
     "INVALID_CONTRACT",
-    "Activity type or status is unsupported"
+    "Activity type, status, or source is unsupported"
   );
   parseIsoTimestamp(entry.occurredAt);
   economyAssert(
@@ -852,13 +866,13 @@ function assertActivityEntry(entry) {
   }
   if (entry.maskedReference !== void 0) {
     economyAssert(
-      entry.maskedReference.length > 0 && entry.maskedReference.length <= 128 && !hasControlCharacters(entry.maskedReference),
+      typeof entry.maskedReference === "string" && entry.maskedReference.length > 0 && entry.maskedReference.length <= 128 && !hasControlCharacters(entry.maskedReference),
       "INVALID_CONTRACT",
       "Masked activity references must be bounded and safe for display"
     );
   }
   economyAssert(
-    entry.sourceLabel.trim().length > 0 && entry.sourceLabel.length <= 128 && !hasControlCharacters(entry.sourceLabel),
+    typeof entry.sourceLabel === "string" && entry.sourceLabel.trim().length > 0 && entry.sourceLabel.length <= 128 && !hasControlCharacters(entry.sourceLabel),
     "INVALID_CONTRACT",
     "Activity source labels must be bounded and safe for display"
   );