@sneat/extension-yardius-contract 0.1.0

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './lib/index.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+// @sneat/extension-yardius-contract — frozen cross-repo contract surface for the yardius extension.
+//
+// Shared DTOs (listings, transaction-log entries, request/claim shapes, the
+// listings-endpoint contract), lifecycle state enums with their legal
+// transition tables, and the listing-visibility ceiling mapping are exported
+// from here so that both the sneat-go backend models and the Sneat super-app
+// extension libs resolve every shared model from this single package. No
+// consumer may re-declare these.
+export * from './lib/index.js';

package/dist/lib/assetus-visibility.d.ts

@@ -0,0 +1,2 @@
+export declare const ASSETUS_VISIBILITIES: readonly ["private", "family", "friends", "friends_of_friends", "specific_space", "public"];
+export type AssetusVisibility = (typeof ASSETUS_VISIBILITIES)[number];

package/dist/lib/assetus-visibility.js

@@ -0,0 +1,19 @@
+// The Assetus asset-visibility values, mirrored here as wire values so the
+// listing-visibility ceiling (see `listing-visibility.ts`) can be encoded as
+// shared data with zero runtime dependencies.
+//
+// Source of truth for the VALUES is the pinned assetus-mvp contract
+// (`AssetVisibility` in the `@sneat/extension-assetus-contract` lib):
+// spec display names `Private` / `Family` / `Friends` / `Friends of Friends` /
+// `Specific Space` / `Public` are persisted as the lowercase snake_case wire
+// values below. Yardius only READS asset visibility (REQ
+// assetus-write-boundary) — this type exists so both the Yardius frontend and
+// backend consume the ceiling mapping from this single package.
+export const ASSETUS_VISIBILITIES = [
+    'private',
+    'family',
+    'friends',
+    'friends_of_friends',
+    'specific_space',
+    'public',
+];

package/dist/lib/borrow-state.d.ts

@@ -0,0 +1,5 @@
+import { StateTransitionTable } from './state-transitions.js';
+export declare const BORROW_STATES: readonly ["available", "requested", "approved", "borrowed", "returned", "closed"];
+export type BorrowState = (typeof BORROW_STATES)[number];
+export declare const BORROW_STATE_TRANSITIONS: StateTransitionTable<BorrowState>;
+export declare function canTransitionBorrow(from: BorrowState, to: BorrowState): boolean;

package/dist/lib/borrow-state.js

@@ -0,0 +1,49 @@
+import { canTransition } from './state-transitions.js';
+// Borrow-listing lifecycle states, per REQ borrow-lifecycle (spec display
+// names `Available → Requested → Approved → Borrowed → Returned → Closed`,
+// persisted as the wire values below):
+//   - 'available' — open, no pending requests;
+//   - 'requested' — ≥1 request pending; the Listing stays visible and accepts
+//     further requests;
+//   - 'approved'  — a member of the owning Space approved exactly one request;
+//     all other pending requests are automatically declined and no further
+//     requests are accepted;
+//   - 'borrowed'  — a member of the owning Space confirmed handover;
+//   - 'returned'  — a member of the owning Space confirmed the item is back;
+//   - 'closed'    — terminal; immediately follows 'returned' (or an
+//     owner-cancel — see REQ owner-cancel).
+export const BORROW_STATES = [
+    'available',
+    'requested',
+    'approved',
+    'borrowed',
+    'returned',
+    'closed',
+];
+// The legal borrow transitions, per REQ borrow-lifecycle + REQ owner-cancel.
+// Any transition not listed here MUST be rejected.
+//
+//   available → requested   first request arrives
+//   available → closed      owner cancels (before 'borrowed' — legal)
+//   requested → approved    owner approves exactly one request
+//   requested → available   the only pending request is withdrawn
+//   requested → closed      owner cancels; all pending requests declined
+//   approved  → borrowed    owner confirms handover
+//   approved  → closed      owner cancels (still before 'borrowed')
+//   borrowed  → returned    owner confirms the item is back; a 'borrowed'
+//                           Listing MUST NOT be cancellable — 'returned' is
+//                           its only exit
+//   returned  → closed      immediate, automatic
+//   closed    → (terminal)
+export const BORROW_STATE_TRANSITIONS = {
+    available: ['requested', 'closed'],
+    requested: ['approved', 'available', 'closed'],
+    approved: ['borrowed', 'closed'],
+    borrowed: ['returned'],
+    returned: ['closed'],
+    closed: [],
+};
+// True when `from → to` is a legal borrow-lifecycle transition.
+export function canTransitionBorrow(from, to) {
+    return canTransition(BORROW_STATE_TRANSITIONS, from, to);
+}

package/dist/lib/giveaway-state.d.ts

@@ -0,0 +1,5 @@
+import { StateTransitionTable } from './state-transitions.js';
+export declare const GIVEAWAY_STATES: readonly ["available", "claimed", "transferred", "closed"];
+export type GiveawayState = (typeof GIVEAWAY_STATES)[number];
+export declare const GIVEAWAY_STATE_TRANSITIONS: StateTransitionTable<GiveawayState>;
+export declare function canTransitionGiveaway(from: GiveawayState, to: GiveawayState): boolean;

package/dist/lib/giveaway-state.js

@@ -0,0 +1,36 @@
+import { canTransition } from './state-transitions.js';
+// Give-away-listing lifecycle states, per REQ giveaway-lifecycle (spec
+// display names `Available → Claimed → Transferred → Closed`, persisted as
+// the wire values below):
+//   - 'available'   — open; eligible viewers claim (claims arriving do NOT
+//     change the state — only the owner's selection does);
+//   - 'claimed'     — a member of the owning Space selected exactly one
+//     claimant; other claims automatically declined;
+//   - 'transferred' — the Assetus ownership transfer to the claimant's Space
+//     succeeded (Assetus appends its own `Transferred` history event); if the
+//     transfer FAILS the Listing stays 'claimed' — staying put is not a
+//     transition;
+//   - 'closed'      — terminal; immediately follows 'transferred' (or an
+//     owner-cancel — see REQ owner-cancel).
+export const GIVEAWAY_STATES = ['available', 'claimed', 'transferred', 'closed'];
+// The legal give-away transitions, per REQ giveaway-lifecycle +
+// REQ owner-cancel. Any transition not listed here MUST be rejected.
+//
+//   available   → claimed      owner selects exactly one claimant
+//   available   → closed       owner cancels (before 'transferred' — legal)
+//   claimed     → transferred  Assetus ownership transfer succeeded on
+//                              confirmed handover (on failure the Listing
+//                              remains 'claimed' — no transition)
+//   claimed     → closed       owner cancels; the claim is declined
+//   transferred → closed       immediate, automatic
+//   closed      → (terminal)
+export const GIVEAWAY_STATE_TRANSITIONS = {
+    available: ['claimed', 'closed'],
+    claimed: ['transferred', 'closed'],
+    transferred: ['closed'],
+    closed: [],
+};
+// True when `from → to` is a legal give-away-lifecycle transition.
+export function canTransitionGiveaway(from, to) {
+    return canTransition(GIVEAWAY_STATE_TRANSITIONS, from, to);
+}

package/dist/lib/index.d.ts

@@ -0,0 +1,9 @@
+export * from './assetus-visibility.js';
+export * from './listing-visibility.js';
+export * from './state-transitions.js';
+export * from './borrow-state.js';
+export * from './giveaway-state.js';
+export * from './listing.js';
+export * from './transaction-log.js';
+export * from './listing-request.js';
+export * from './listings-endpoint.js';

package/dist/lib/index.js

@@ -0,0 +1,9 @@
+export * from './assetus-visibility.js';
+export * from './listing-visibility.js';
+export * from './state-transitions.js';
+export * from './borrow-state.js';
+export * from './giveaway-state.js';
+export * from './listing.js';
+export * from './transaction-log.js';
+export * from './listing-request.js';
+export * from './listings-endpoint.js';

package/dist/lib/listing-request.d.ts

@@ -0,0 +1,11 @@
+export declare const LISTING_REQUEST_STATUSES: readonly ["pending", "approved", "declined", "withdrawn"];
+export type ListingRequestStatus = (typeof LISTING_REQUEST_STATUSES)[number];
+export interface IListingRequestDto {
+    readonly id: string;
+    readonly requesterSpaceID: string;
+    readonly requesterMemberID: string;
+    readonly requesterTitle?: string;
+    readonly requesterSpaceTitle?: string;
+    readonly status: ListingRequestStatus;
+    readonly createdAt: string;
+}

package/dist/lib/listing-request.js

@@ -0,0 +1,17 @@
+// Status of a borrow request or give-away claim:
+//   - 'pending'   — awaiting the owning Space's decision;
+//   - 'approved'  — the owner approved this request (borrow) or selected this
+//     claimant (give-away); all other pending requests/claims on the Listing
+//     are automatically declined (REQ borrow-lifecycle /
+//     REQ giveaway-lifecycle);
+//   - 'declined'  — declined by the owner, auto-declined because another
+//     request was approved, cancelled with the Listing (REQ owner-cancel), or
+//     auto-declined on friendship removal (REQ friendship-removal);
+//   - 'withdrawn' — the requester withdrew their own pending request
+//     (REQ borrow-request).
+export const LISTING_REQUEST_STATUSES = [
+    'pending',
+    'approved',
+    'declined',
+    'withdrawn',
+];

package/dist/lib/listing-visibility.d.ts

@@ -0,0 +1,7 @@
+import { AssetusVisibility } from './assetus-visibility.js';
+export declare const LISTING_VISIBILITIES: readonly ["private", "members", "friends"];
+export type ListingVisibility = (typeof LISTING_VISIBILITIES)[number];
+export declare const DEFAULT_LISTING_VISIBILITY: ListingVisibility;
+export declare const LISTING_VISIBILITY_CEILING: Readonly<Record<AssetusVisibility, readonly ListingVisibility[]>>;
+export declare function allowedListingVisibilities(assetVisibility: AssetusVisibility): readonly ListingVisibility[];
+export declare function isListingVisibilityAllowed(assetVisibility: AssetusVisibility, listingVisibility: ListingVisibility): boolean;

package/dist/lib/listing-visibility.js

@@ -0,0 +1,44 @@
+// A Listing's own visibility, per REQ listing-visibility-ceiling (spec display
+// names `Private` / `Members` / `Friends`, persisted as the wire values
+// below):
+//   - 'private' — visible only to members of the owning Space;
+//   - 'members' — visible to members of the owning Space (reserved distinction
+//     from 'private' for future member-subset control; in MVP the two resolve
+//     to the same audience, and 'members' is the default);
+//   - 'friends' — additionally visible to members of befriended Spaces.
+export const LISTING_VISIBILITIES = ['private', 'members', 'friends'];
+// Per REQ listing-visibility-ceiling: `members` is the default listing
+// visibility.
+export const DEFAULT_LISTING_VISIBILITY = 'members';
+// The asset's Assetus visibility is a CEILING on the listing's visibility,
+// per this exact mapping from REQ listing-visibility-ceiling:
+//
+//   | Asset visibility (Assetus)               | Permitted listing visibilities |
+//   |------------------------------------------|--------------------------------|
+//   | Private                                  | Private                        |
+//   | Family                                   | Private, Members               |
+//   | Specific Space                           | Private (MVP simplification)   |
+//   | Friends, Friends of Friends, Public      | Private, Members, Friends      |
+//
+// Encoded as data so frontend and backend enforce the same source of truth.
+// Publishing with a listing visibility not permitted here MUST be rejected
+// with an actionable error telling the user to raise the asset's visibility
+// in Assetus first.
+export const LISTING_VISIBILITY_CEILING = {
+    private: ['private'],
+    family: ['private', 'members'],
+    specific_space: ['private'], // MVP simplification.
+    friends: ['private', 'members', 'friends'],
+    friends_of_friends: ['private', 'members', 'friends'],
+    public: ['private', 'members', 'friends'],
+};
+// The listing visibilities permitted for an asset with the given Assetus
+// visibility. Pure lookup over `LISTING_VISIBILITY_CEILING`.
+export function allowedListingVisibilities(assetVisibility) {
+    return LISTING_VISIBILITY_CEILING[assetVisibility];
+}
+// True when a listing with `listingVisibility` may be published for an asset
+// whose Assetus visibility is `assetVisibility`.
+export function isListingVisibilityAllowed(assetVisibility, listingVisibility) {
+    return LISTING_VISIBILITY_CEILING[assetVisibility].includes(listingVisibility);
+}

package/dist/lib/listing.d.ts

@@ -0,0 +1,22 @@
+import { BorrowState } from './borrow-state.js';
+import { GiveawayState } from './giveaway-state.js';
+import { ListingVisibility } from './listing-visibility.js';
+export declare const LISTING_TYPES: readonly ["borrow", "giveaway"];
+export type ListingType = (typeof LISTING_TYPES)[number];
+export type ListingState = BorrowState | GiveawayState;
+interface IListingBase {
+    readonly id: string;
+    readonly spaceID: string;
+    readonly assetID: string;
+    readonly visibility: ListingVisibility;
+}
+export interface IBorrowListingDto extends IListingBase {
+    readonly type: 'borrow';
+    readonly state: BorrowState;
+}
+export interface IGiveawayListingDto extends IListingBase {
+    readonly type: 'giveaway';
+    readonly state: GiveawayState;
+}
+export type IListingDto = IBorrowListingDto | IGiveawayListingDto;
+export {};

package/dist/lib/listing.js

@@ -0,0 +1,3 @@
+// A Listing's transaction type, per REQ publish-listing: exactly `borrow` or
+// `giveaway`. Sell / swap / reserve are explicitly out of MVP scope.
+export const LISTING_TYPES = ['borrow', 'giveaway'];

package/dist/lib/listings-endpoint.d.ts

@@ -0,0 +1,12 @@
+import { IListingDto } from './listing.js';
+export type IGetListingsRequest = Record<string, never>;
+export type ListingsGroupReason = 'member' | 'friend';
+export interface IListingsSpaceGroup {
+    readonly spaceID: string;
+    readonly spaceTitle: string;
+    readonly reason: ListingsGroupReason;
+    readonly listings: readonly IListingDto[];
+}
+export interface IGetListingsResponse {
+    readonly groups: readonly IListingsSpaceGroup[];
+}

package/dist/lib/listings-endpoint.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/state-transitions.d.ts

@@ -0,0 +1,2 @@
+export type StateTransitionTable<TState extends string> = Readonly<Record<TState, readonly TState[]>>;
+export declare function canTransition<TState extends string>(table: StateTransitionTable<TState>, from: TState, to: TState): boolean;

package/dist/lib/state-transitions.js

@@ -0,0 +1,7 @@
+// True when `from → to` is a legal transition per the given table. Pure and
+// dependency-free by design; a state never legally "transitions" to itself
+// (staying put — e.g. a give-away remaining `claimed` after a failed Assetus
+// transfer — is the absence of a transition, not a transition).
+export function canTransition(table, from, to) {
+    return table[from].includes(to);
+}

package/dist/lib/transaction-log.d.ts

@@ -0,0 +1,8 @@
+export declare const YARDIUS_EVENT_TYPES: readonly ["publish", "request", "withdraw", "approve", "decline", "handover", "return", "claim", "transfer", "cancel"];
+export type YardiusEventType = (typeof YARDIUS_EVENT_TYPES)[number];
+export interface ITransactionLogEntry {
+    readonly event: YardiusEventType;
+    readonly at: string;
+    readonly actingMemberSpaceID: string;
+    readonly actingMemberID: string;
+}

package/dist/lib/transaction-log.js

@@ -0,0 +1,14 @@
+// The exact set of lifecycle event types recorded in a Listing's per-listing
+// transaction log, per REQ transaction-log.
+export const YARDIUS_EVENT_TYPES = [
+    'publish',
+    'request',
+    'withdraw',
+    'approve',
+    'decline',
+    'handover',
+    'return',
+    'claim',
+    'transfer',
+    'cancel',
+];

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@sneat/extension-yardius-contract",
+  "version": "0.1.0",
+  "description": "Frozen cross-repo contract surface (shared DTOs, consts, briefs) for the yardius Sneat extension",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sneat-co/ext-yardius.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@nx/js": "22.7.5",
+    "nx": "22.7.5",
+    "typescript": "~5.9.3",
+    "vite": "^7.2.7",
+    "vitest": "4.0.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}