@solarpunkltd/swarm-id 0.0.0-stage → 0.8.1

package/dist/utils/account-state-snapshot.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Account State Snapshot Module
+ *
+ * The in-memory account-state snapshot: what sync captures before building a
+ * device view, and what the account bus carries as an `account-delta`.
+ * `serializeAccountStateSnapshot` is the delta's wire form; the receiver
+ * validates it with `AccountStateSnapshotSchemaV1` (`bus/messages.ts`).
+ */
+import type { ConnectedApp, PostageStamp, AccountMetadata, AccountStateSnapshot, SyncedAccount } from "../schemas";
+export type { AccountStateSnapshot } from "../schemas";
+/**
+ * The account record as an account-state snapshot — the ONE assembly every
+ * publisher shares (the sync coordinator's feed write, the proxy's feed write,
+ * the proxy's `account-delta`, and the fold that consumes one).
+ *
+ * `timestamp` is the caller's clock for this snapshot, used for both the
+ * envelope and `metadata.lastModified`: a publisher passes `Date.now()`, a
+ * caller re-reading a record it did not just change passes that record's own
+ * `lastModified` rather than restamping it.
+ *
+ * Every never-edited scalar clock falls back to the account's STABLE
+ * `createdAt`, NEVER a fresh `Date.now()`: re-stamping an unchanged name /
+ * default-stamp / settings on every publish would let a device that never
+ * touched the field clobber a peer's genuine concurrent edit under per-field
+ * LWW (docs/Account-State.md, "Convergence rules"). `createdAt` is identical
+ * across devices and predates every edit,
+ * so any real change still wins.
+ *
+ * `defaultPostageStampBatchID` may be absent: an account with no drives is a
+ * supported state, and only the feed write (which needs a stamp to pay for
+ * itself) may treat that as a reason not to publish.
+ */
+export declare function accountToStateSnapshot(account: SyncedAccount, accountId: string, timestamp: number): AccountStateSnapshot;
+/**
+ * Serialize account data into a plain object suitable for JSON encoding.
+ */
+export declare function serializeAccountStateSnapshot(input: {
+    accountId: string;
+    metadata: AccountMetadata;
+    connectedApps: ConnectedApp[];
+    postageStamps: PostageStamp[];
+    timestamp: number;
+}): Record<string, unknown>;

package/dist/utils/active-devices.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The registry half of the partition-contention rival set: devices that
+ * signed in recently enough to plausibly be acquiring RIGHT NOW.
+ *
+ * The other half is the account bus. A device beating `presence` in the room
+ * (`bus/presence.ts`) is alive by construction, and every caller unions that
+ * set with this one; this filter is the bootstrap for a context with no bus,
+ * and for a device that signed in moments ago and has not beaten yet.
+ *
+ * The intent round reads every known device's per-device intent address to
+ * deconflict simultaneous fresh claims. If that set is "all devices the account
+ * ever saw", long-dead devices (ghosts from old sessions — the device list is
+ * append-only and never pruned) each add an absent network read to every
+ * acquire; on a flaky gateway that cost can push a single acquire past its
+ * timeout, so a live device can't even claim a FREE partition. A non-active
+ * device must not be able to influence an active one.
+ *
+ * Filtering by `lastSignedInAt` recency is SAFE (not a correctness mechanism)
+ * because the deviceId-INDEPENDENT occupancy beacon, which is NOT gated on this
+ * set, is the real dual-acquire backstop for a live peer that this prune drops:
+ *   - `PartitionLease.refreshHoldersFromOccupancy` (in `acquire`) catches a peer
+ *     that already HOLDS a partition; and
+ *   - `PartitionLease.occupancyBeaconBeatsUs` (in `refresh`) resolves a symmetric
+ *     fresh-claim dual-acquire with such a peer.
+ * `lastSignedInAt` advances only on an actual SIGN-IN (a creation or a
+ * reactivation), never on a poll (#652) — so a long-running device IS pruned
+ * from THIS half after the window; the bus half is what keeps it a rival, and
+ * the occupancy channel is what keeps that safe. Pruning only removes the
+ * per-acquire absent-read cost of dead ghosts.
+ */
+import type { Device } from "../schemas";
+/**
+ * How recently a device must have signed in to count as a contention rival
+ * without a bus beat. The stamp is frozen at sign-in (#652), so this bounds the
+ * age of the SESSION, not any publish cadence: long enough that a device which
+ * just signed in is a rival through its first acquires, far below a prior
+ * session, so stale ghosts are dropped. A live device past the window stays a
+ * rival through the bus half, not this one.
+ */
+export declare const KNOWN_DEVICE_MAX_AGE_MS: number;
+/**
+ * Device ids that are (a) not removed and (b) signed in within `maxAgeMs` of
+ * `nowMs`. A missing `lastSignedInAt` counts as stale.
+ */
+export declare function activeDeviceIds(devices: Device[], nowMs: number, maxAgeMs: number): string[];

package/dist/utils/avatar.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Account avatars. Every account has one generated from its id, which
+ * {@link Avatar.source} reports — leaving room for another kind of image
+ * should one ever be added.
+ *
+ * The generator is Polycon by Christian Montoya
+ * (https://github.com/Montoya/polycon). Original algorithm: SDBM hash → 2×2
+ * grid of triangles/squares with color pairs. Adapted here with a custom brand
+ * color palette.
+ */
+import type { Avatar } from "../types";
+/**
+ * Render an account's generated avatar as a standalone SVG string.
+ *
+ * The same seed always yields the same image, so a dApp passing the identity
+ * id from `ConnectionInfo` renders exactly the avatar Swarm ID shows for that
+ * account. Prefer `SwarmIdClient.getAvatar()`, which falls back to this only
+ * while the account has no avatar of its own.
+ *
+ * @param seed - Value the avatar is derived from (e.g. `connectionInfo.identity.id`)
+ * @param size - Width and height in pixels
+ */
+export declare function generatedAvatarSvg(seed: string, size?: number): string;
+/**
+ * The generated avatar for `seed` as a renderable {@link Avatar}.
+ *
+ * @param seed - Value the avatar is derived from (e.g. `connectionInfo.identity.id`)
+ * @param size - Width and height in pixels
+ */
+export declare function generatedAvatar(seed: string, size?: number): Avatar;