@voltro/plugin-inventory 0.0.0-stage → 0.87.0

package/dist/testing.d.ts

@@ -0,0 +1,448 @@
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { Layer } from 'effect';
+import { Layer as Layer_2 } from 'effect/Layer';
+import { PluginPrivacyTarget } from '@voltro/protocol';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+export declare const catalogFakeLayer: Layer_2<InventoryPort | CraftingPort | CatalogSource, never, never>;
+
+/** Serializable content uses a declared item's version, never a stored Schema object. */
+declare interface CatalogItem {
+    readonly id: string;
+    readonly schemaVersion: number;
+    readonly kind: ItemKind;
+    readonly stackable: boolean;
+    readonly maxStack: number;
+    readonly tradable: boolean;
+    readonly rarity: string;
+    readonly tags: readonly string[];
+    readonly equipSlot: string | null;
+    readonly expiresAfter: number | null;
+    readonly display: {
+        readonly nameKey: string;
+        readonly icon: string | null;
+    };
+    readonly attributes: JsonValue;
+    readonly instanceDefaults: JsonValue;
+}
+
+declare interface CatalogScope {
+    readonly tenantId: string;
+    readonly channel: string;
+    readonly locale: string;
+}
+
+declare interface CatalogSnapshot {
+    readonly revision: string;
+    readonly items: readonly CatalogItem[];
+}
+
+declare class CatalogSource extends CatalogSource_base {
+}
+
+declare const CatalogSource_base: Context.ServiceClass<CatalogSource, "@voltro/CatalogSource", CatalogSourceService>;
+
+/** Read only. Call at join/workflow boundaries, never from a room tick. */
+declare interface CatalogSourceService {
+    readonly read: (scope: CatalogScope) => Effect.Effect<CatalogSnapshot, InventoryError>;
+}
+
+export declare const catalogSourceSystemFixture: Readonly<{
+    kind: "port";
+    tag: typeof CatalogSource;
+    fakeLayer: Layer_2<InventoryPort | CraftingPort | CatalogSource, never, never>;
+    probe: {
+        run: () => Effect.Effect<{
+            revision: string;
+            items: string[];
+        }, InventoryError, never>;
+        expected: {
+            revision: string;
+            items: string[];
+        };
+    };
+}>;
+
+/** Uses the actual recipe declaration; amounts are illustrative fixture rules. */
+export declare const craftFixture: () => Readonly<{
+    recipe: Recipe;
+    batches: 1;
+    at: number;
+    available: readonly Readonly<{
+        id: "fixture.potion";
+        itemId: "test.potion";
+        schemaVersion: 1;
+        qty: 6;
+        attributes: Readonly<{}>;
+        acquiredAt: number;
+        expiresAt: null;
+        locked: false;
+        source: "fixture";
+    }>[];
+    excludedIds: readonly never[];
+}>;
+
+export declare const craftingFakeLayer: Layer_2<InventoryPort | CraftingPort | CatalogSource, never, never>;
+
+declare class CraftingPort extends CraftingPort_base {
+}
+
+declare const CraftingPort_base: Context.ServiceClass<CraftingPort, "@voltro/CraftingPort", CraftingService>;
+
+export declare const craftingPortSystemFixture: Readonly<{
+    kind: "port";
+    tag: typeof CraftingPort;
+    fakeLayer: Layer_2<InventoryPort | CraftingPort | CatalogSource, never, never>;
+    probe: {
+        run: () => Effect.Effect<{
+            original: boolean;
+            quantity: number;
+        }, InventoryError, never>;
+        expected: {
+            original: boolean;
+            quantity: number;
+        };
+    };
+}>;
+
+/** Small independent seam; InventoryPort retains its eight-method surface. */
+declare interface CraftingService {
+    readonly craft: (subject: Subject, input: CraftRequest) => Effect.Effect<InventoryReceipt, InventoryError>;
+    readonly recipes: (subject: Subject) => Effect.Effect<readonly Recipe[], InventoryError>;
+    readonly exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, InventoryError>;
+    readonly eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, InventoryError>;
+}
+
+declare interface CraftInput {
+    readonly recipe: Recipe;
+    readonly batches: number;
+    readonly at: number;
+    readonly available: readonly InventoryInstance[];
+    readonly excludedIds: readonly string[];
+}
+
+declare interface CraftPlan {
+    readonly consume: readonly {
+        readonly instanceId: string;
+        readonly qty: number;
+    }[];
+    readonly outputs: readonly RecipeOutput[];
+}
+
+declare interface CraftRequest {
+    readonly tenantId: string;
+    readonly owner: InventoryOwner;
+    readonly recipeId: string;
+    readonly requestId: string;
+    readonly batches?: number;
+}
+
+declare type CraftResolver = (input: CraftInput) => CraftPlan;
+
+export declare const craftResolverSystemFixture: Readonly<{
+    kind: "slot";
+    defaultImplementation: CraftResolver;
+    defaultProbe: {
+        run: () => Effect.Effect< CraftPlan, never, never>;
+        expected: {
+            consume: {
+                instanceId: string;
+                qty: number;
+            }[];
+            outputs: {
+                itemId: string;
+                qty: number;
+            }[];
+        };
+    };
+    overrideProbe: {
+        run: () => Effect.Effect< CraftPlan, never, never>;
+        expected: {
+            consume: {
+                instanceId: string;
+                qty: number;
+            }[];
+            outputs: {
+                itemId: string;
+                qty: number;
+            }[];
+        };
+    };
+}>;
+
+declare interface ExpiryInput {
+    readonly item: CatalogItem;
+    readonly acquiredAt: number;
+}
+
+declare type ExpiryPolicy = (input: ExpiryInput) => number | null;
+
+export declare const expiryPolicySystemFixture: Readonly<{
+    kind: "slot";
+    defaultImplementation: ExpiryPolicy;
+    defaultProbe: {
+        run: () => Effect.Effect<number | null, never, never>;
+        expected: null;
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<number | null, never, never>;
+        expected: number;
+    };
+}>;
+
+declare interface InventoryConsume {
+    readonly tenantId: string;
+    readonly owner: InventoryOwner;
+    readonly requestId: string;
+    readonly instanceId: string;
+    readonly qty: number;
+    readonly reason: string;
+    readonly ref: InventoryRef;
+}
+
+declare interface InventoryEquip {
+    readonly slotSet: string;
+    readonly slot: string;
+    readonly instanceId: string | null;
+    readonly requestId: string;
+}
+
+/** Public errors carry codes, never subjects, catalog values or provider causes. */
+declare class InventoryError extends InventoryError_base {
+}
+
+declare const InventoryError_base: Schema.Class<InventoryError, Schema.TaggedStruct<"InventoryError", {
+    readonly code: Schema.Literals<readonly ["invalid_input", "invalid_record", "invalid_item", "invalid_attributes", "conflict", "forbidden", "not_found", "unavailable", "limit_exceeded", "erased", "insufficient_items", "insufficient_funds", "payment_refused", "locked", "expired", "invalid_slot"]>;
+}>, YieldableError>;
+
+declare interface InventoryExpire {
+    readonly tenantId: string;
+    readonly owner: InventoryOwner;
+    readonly requestId: string;
+    readonly until: number;
+}
+
+export declare const inventoryFakeLayer: Layer_2<InventoryPort | CraftingPort | CatalogSource, never, never>;
+
+/** Illustrative fixtures invoke the exported runtime contract and content validator. */
+export declare const inventoryFixture: () => Readonly<{
+    item: ItemContract;
+    content: CatalogItem;
+    stack: Readonly<{
+        item: CatalogItem;
+        quantity: 12;
+        available: readonly {
+            id: string;
+            quantity: number;
+        }[];
+    }>;
+    expiry: Readonly<{
+        item: CatalogItem;
+        acquiredAt: number;
+    }>;
+}>;
+
+declare interface InventoryGrant {
+    readonly tenantId: string;
+    readonly owner: InventoryOwner;
+    readonly requestId: string;
+    readonly itemId: string;
+    readonly qty: number;
+    readonly attributes?: JsonValue;
+    readonly reason: string;
+    readonly ref: InventoryRef;
+}
+
+declare interface InventoryInstance {
+    readonly id: string;
+    readonly itemId: string;
+    readonly schemaVersion: number;
+    readonly qty: number;
+    readonly attributes: JsonValue;
+    readonly acquiredAt: number;
+    readonly expiresAt: number | null;
+    readonly locked: boolean;
+    readonly source: string;
+}
+
+declare interface InventoryLoadout {
+    readonly slotSet: string;
+    readonly slot: string;
+    readonly instanceId: string;
+}
+
+declare interface InventoryOwner {
+    readonly ownerKind: 'player' | 'guild';
+    readonly ownerId: string;
+}
+
+declare class InventoryPort extends InventoryPort_base {
+}
+
+declare const InventoryPort_base: Context.ServiceClass<InventoryPort, "@voltro/InventoryPort", InventoryService>;
+
+/** Explicit test-only scoped Layer; actual SQL-owned writers on one private InMemoryDataStore, never a production backend. */
+export declare function inventoryPortFixture(input: InventoryPortFixtureOptions & {
+    readonly recipes: readonly Recipe[];
+}): Readonly<{
+    layer: Layer.Layer<InventoryPort | CatalogSource | CraftingPort>;
+}>;
+
+export declare function inventoryPortFixture(input: InventoryPortFixtureOptions): Readonly<{
+    layer: Layer.Layer<InventoryPort | CatalogSource>;
+}>;
+
+export declare interface InventoryPortFixtureOptions {
+    readonly tenantId: string;
+    readonly items: readonly ItemDefinition[];
+    readonly content: readonly CatalogItem[];
+    readonly recipes?: readonly Recipe[];
+    readonly slotSets?: Readonly<Record<string, readonly string[]>>;
+    readonly now?: () => number;
+}
+
+export declare const inventoryPortSystemFixture: Readonly<{
+    kind: "port";
+    tag: typeof InventoryPort;
+    fakeLayer: Layer_2<InventoryPort | CraftingPort | CatalogSource, never, never>;
+    probe: {
+        run: () => Effect.Effect<number, InventoryError, never>;
+        expected: number;
+    };
+}>;
+
+declare interface InventoryReceipt {
+    readonly operationId: string;
+    readonly kind: 'grant' | 'consume' | 'equip' | 'expire' | 'craft' | 'reserve' | 'release' | 'transfer-out' | 'transfer-in';
+    readonly changes: readonly {
+        readonly instanceId: string;
+        readonly delta: number;
+    }[];
+    readonly at: number;
+}
+
+declare interface InventoryRef {
+    readonly kind: string;
+    readonly id: string;
+}
+
+/** Installed routes and trusted callers use this same replaceable service. */
+declare interface InventoryService {
+    readonly grant: (subject: Subject, input: InventoryGrant) => Effect.Effect<InventoryReceipt, InventoryError>;
+    readonly consume: (subject: Subject, input: InventoryConsume) => Effect.Effect<InventoryReceipt, InventoryError>;
+    readonly mine: (subject: Subject) => Effect.Effect<readonly InventoryInstance[], InventoryError>;
+    readonly loadout: (subject: Subject, slotSet: string) => Effect.Effect<readonly InventoryLoadout[], InventoryError>;
+    readonly equip: (subject: Subject, input: InventoryEquip) => Effect.Effect<InventoryReceipt, InventoryError>;
+    readonly expire: (subject: Subject, input: InventoryExpire) => Effect.Effect<InventoryReceipt, InventoryError>;
+    readonly exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, InventoryError>;
+    readonly eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, InventoryError>;
+}
+
+declare const ITEM_KINDS: readonly ["consumable", "equipment", "cosmetic", "currencyBundle", "key", "mod"];
+
+declare interface ItemContract extends Omit<ItemDefinition, 'schemaVersion' | 'equipSlot' | 'expiresAfter' | 'display'> {
+    readonly schemaVersion: number;
+    readonly equipSlot: string | null;
+    readonly expiresAfter: number | null;
+    readonly display: {
+        readonly nameKey: string;
+        readonly icon: string | null;
+    };
+}
+
+declare interface ItemDefinition {
+    readonly id: string;
+    readonly kind: ItemKind;
+    readonly schemaVersion?: number;
+    readonly stackable: boolean;
+    readonly maxStack: number;
+    readonly tradable: boolean;
+    readonly rarity: string;
+    readonly tags: readonly string[];
+    readonly attributes: Schema.Top;
+    readonly instanceAttributes: Schema.Top;
+    readonly equipSlot?: string | null;
+    /** Milliseconds; resolved on grant, never by a tick. */
+    readonly expiresAfter?: number | null;
+    readonly display: {
+        readonly nameKey: string;
+        readonly icon?: string | null;
+    };
+}
+
+declare type ItemKind = typeof ITEM_KINDS[number];
+
+declare type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+
+declare interface Recipe {
+    readonly id: string;
+    readonly version: number;
+    readonly inputs: readonly RecipeIngredient[];
+    readonly outputs: readonly RecipeOutput[];
+    readonly maxBatches: number;
+    readonly cost: RecipeCurrencyCost | null;
+    readonly timeMs: 0;
+    readonly requires: null;
+}
+
+declare interface RecipeCurrencyCost {
+    readonly currency: string;
+    readonly amount: string;
+}
+
+declare interface RecipeIngredient {
+    readonly itemId: string;
+    readonly qty: number;
+}
+
+declare interface RecipeOutput extends RecipeIngredient {
+    readonly attributes?: JsonValue;
+}
+
+declare interface StackInput {
+    readonly item: CatalogItem;
+    readonly quantity: number;
+    readonly available: readonly {
+        readonly id: string;
+        readonly quantity: number;
+    }[];
+}
+
+declare interface StackPlan {
+    readonly existing: readonly {
+        readonly id: string;
+        readonly add: number;
+    }[];
+    readonly create: readonly number[];
+}
+
+declare type StackPolicy = (input: StackInput) => StackPlan;
+
+export declare const stackPolicySystemFixture: Readonly<{
+    kind: "slot";
+    defaultImplementation: StackPolicy;
+    defaultProbe: {
+        run: () => Effect.Effect< StackPlan, never, never>;
+        expected: {
+            existing: {
+                id: string;
+                add: number;
+            }[];
+            create: number[];
+        };
+    };
+    overrideProbe: {
+        run: () => Effect.Effect< StackPlan, never, never>;
+        expected: {
+            existing: never[];
+            create: number[];
+        };
+    };
+}>;
+
+export { }

package/dist/testing.js

@@ -0,0 +1,4 @@
+import { craftFixture as e, inventoryFixture as t } from "./declarationFixtures.js";
+import { inventoryPortFixture as n } from "./inventoryPort.fixture.js";
+import { catalogFakeLayer as r, catalogSourceSystemFixture as i, craftResolverSystemFixture as a, craftingFakeLayer as o, craftingPortSystemFixture as s, expiryPolicySystemFixture as c, inventoryFakeLayer as l, inventoryPortSystemFixture as u, stackPolicySystemFixture as d } from "./systemFixtures.js";
+export { r as catalogFakeLayer, i as catalogSourceSystemFixture, e as craftFixture, a as craftResolverSystemFixture, o as craftingFakeLayer, s as craftingPortSystemFixture, c as expiryPolicySystemFixture, l as inventoryFakeLayer, t as inventoryFixture, n as inventoryPortFixture, u as inventoryPortSystemFixture, d as stackPolicySystemFixture };

package/dist/web.d.ts

@@ -0,0 +1,60 @@
+import { ActionState } from '@voltro/client';
+import { SubscriptionState } from '@voltro/client';
+
+export declare const useCatalog: (apiName?: string) => SubscriptionState<{
+    readonly revision: string;
+    readonly items: readonly {
+        readonly id: string;
+        readonly schemaVersion: number;
+        readonly kind: "key" | "consumable" | "equipment" | "cosmetic" | "currencyBundle" | "mod";
+        readonly stackable: boolean;
+        readonly maxStack: number;
+        readonly tradable: boolean;
+        readonly rarity: string;
+        readonly tags: readonly string[];
+        readonly equipSlot: string | null;
+        readonly expiresAfter: number | null;
+        readonly display: {
+            readonly nameKey: string;
+            readonly icon: string | null;
+        };
+        readonly attributes: unknown;
+        readonly instanceDefaults: unknown;
+    }[];
+}>;
+
+export declare const useInventory: (apiName?: string) => SubscriptionState<readonly {
+    readonly id: string;
+    readonly itemId: string;
+    readonly schemaVersion: number;
+    readonly qty: number;
+    readonly attributes: unknown;
+    readonly acquiredAt: number;
+    readonly expiresAt: number | null;
+    readonly locked: boolean;
+    readonly source: string;
+}[]>;
+
+/** Sends only the declared equip intention; the own live subscriptions supply accepted state. */
+export declare const useInventoryEquip: (apiName?: string) => ActionState<{
+    readonly slotSet: string;
+    readonly slot: string;
+    readonly instanceId: string | null;
+    readonly requestId: string;
+}, {
+    readonly operationId: string;
+    readonly kind: "grant" | "expire" | "release" | "reserve" | "consume" | "equip" | "craft" | "transfer-out" | "transfer-in";
+    readonly changes: readonly {
+        readonly instanceId: string;
+        readonly delta: number;
+    }[];
+    readonly at: number;
+}>;
+
+export declare const useLoadout: (slotSet: string, apiName?: string) => SubscriptionState<readonly {
+    readonly slotSet: string;
+    readonly slot: string;
+    readonly instanceId: string;
+}[]>;
+
+export { }

package/dist/web.js

@@ -0,0 +1,7 @@
+import { INVENTORY_NAME as e } from "./rpc.js";
+import { pluginTag as t } from "@voltro/protocol";
+import { useAction as n, useSubscription as r } from "@voltro/client";
+//#region src/web.ts
+var i = (n = "app") => r(n, t(e, "mine"), {}), a = (n, i = "app") => r(i, t(e, "loadout"), { slotSet: n }), o = (n = "app") => r(n, t(e, "catalog"), {}), s = (r = "app") => n(r, t(e, "equip"));
+//#endregion
+export { o as useCatalog, i as useInventory, s as useInventoryEquip, a as useLoadout };

package/package.json

@@ -1,6 +1,106 @@
 {
   "name": "@voltro/plugin-inventory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.87.0",
+  "description": "Versioned catalogs, SQL-owned item grants and consumption, bounded stacks, equip intentions and privacy fences.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js",
+      "default": "./dist/errors.js"
+    },
+    "./catalog": {
+      "types": "./dist/catalog.d.ts",
+      "import": "./dist/catalog.js",
+      "default": "./dist/catalog.js"
+    },
+    "./items": {
+      "types": "./dist/item.d.ts",
+      "import": "./dist/item.js",
+      "default": "./dist/item.js"
+    },
+    "./strategies": {
+      "types": "./dist/strategies.d.ts",
+      "import": "./dist/strategies.js",
+      "default": "./dist/strategies.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./cms": {
+      "types": "./dist/cmsCatalog.d.ts",
+      "import": "./dist/cmsCatalog.js",
+      "default": "./dist/cmsCatalog.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
+    },
+    "./rpc": {
+      "types": "./dist/rpc.d.ts",
+      "import": "./dist/rpc.js",
+      "default": "./dist/rpc.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "import": "./dist/web.js",
+      "default": "./dist/web.js"
+    },
+    "./package.json": "./package.json",
+    "./crafting": {
+      "types": "./dist/crafting.d.ts",
+      "import": "./dist/crafting.js",
+      "default": "./dist/crafting.js"
+    },
+    "./components": {
+      "types": "./dist/components.d.ts",
+      "import": "./dist/components.js",
+      "default": "./dist/components.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/database": "0.87.0",
+    "@voltro/protocol": "0.87.0",
+    "@voltro/client": "0.87.0",
+    "@voltro/cms": "0.87.0",
+    "@voltro/ui-shadcn": "0.87.0",
+    "@voltro/runtime": "0.87.0",
+    "@voltro/plugin-licensing": "0.87.0"
+  },
+  "peerDependencies": {
+    "effect": "4.0.1",
+    "react": "^19.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}