@estiva-app/interop 0.31.0 → 0.32.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/CHANGELOG.md CHANGED
@@ -6,6 +6,29 @@ how a declaration is read, is a MAJOR — in `0.x`, a MINOR — even when no
6
6
  TypeScript signature moved. A consumer upgrading must be able to tell whether
7
7
  manifests already published still mean what they meant.
8
8
 
9
+ ## 0.32.0 — 2026-09-24
10
+
11
+ **Manifests: nothing.** No declaration is read differently. What is new is
12
+ the write side of Folders, which until now each app wrote for itself.
13
+
14
+ - **Folder write planners** (FOL-4): `planCreateFolder`, `planRenameFolder`,
15
+ `planPlaceFile`, `planUnlistFile` and `planMoveFile`. Each returns unsigned
16
+ events in publish order and does no signing, no I/O and no clock or id
17
+ generation; each app keeps its own signing and publishing (ADR 0002 §10 —
18
+ Ship is the second app to write these).
19
+ - create = `[9007, 1852 add + name]`, so a Folder has state from birth;
20
+ - rename = `[9002, 1852 add + name]`, the command only when it has state;
21
+ - place / unlist = `[1852 add]` / `[1852 remove]` only when it has state;
22
+ - move = `[add to target, remove from source]`, add first.
23
+ - **`hasState` is always the caller's**, from a read. A `kind:1852` against a
24
+ Folder with no `kind:30890` emits state listing only what the command named,
25
+ and everything filed in it by `h` stops being listed (peek#192). So **a move
26
+ into or out of a stateless Folder is refused** — `{ ok: false, reason:
27
+ 'source-has-no-state' | 'target-has-no-state' }` — where Peek's own move
28
+ sent both commands regardless.
29
+ - **Peer dependency: `@estiva-app/protocol >= 0.23.0`**, for
30
+ `buildFolderCommand`. Nothing else in this package needed it raised.
31
+
9
32
  ## 0.31.0 — 2026-09-23
10
33
 
11
34
  **Manifests: nothing.** No declaration is read differently. What is new is a
package/README.md CHANGED
@@ -500,6 +500,32 @@ channel's `listedIn` is every Folder that lists the project, so an unread
500
500
  verdict on it has a team to reach. It costs one more request, for the records.
501
501
  A channel with state of its own is a Folder, and only states place it.
502
502
 
503
+ ### Changing a folder
504
+
505
+ ```ts
506
+ import { planMoveFile } from '@estiva-app/interop'
507
+
508
+ const plan = planMoveFile(me, Date.now(), {
509
+ address,
510
+ from: { id: here.id, hasState: here.hasState }, // from a read, never a guess
511
+ to: { id: there.id, hasState: there.hasState },
512
+ })
513
+ if (!plan.ok) return plan.reason // 'source-has-no-state' | 'target-has-no-state'
514
+ for (const event of plan.events) { // publish in order; stop at the first refusal
515
+ if (!(await publish(await sign(event))).ok) break
516
+ }
517
+ ```
518
+
519
+ `planCreateFolder`, `planRenameFolder`, `planPlaceFile`, `planUnlistFile` and
520
+ `planMoveFile` return **unsigned** events in publish order. Signing and
521
+ publishing stay yours.
522
+
523
+ Every one but create takes `hasState`, because the relay computes a folder's
524
+ next state from its current one and a folder with no `kind:30890` has none: a
525
+ `kind:1852` against it emits state listing only what the command named, and
526
+ everything filed in it by `h` stops being listed. So rename, place and unlist
527
+ send no command to such a folder, and a move into or out of one is refused.
528
+
503
529
  ---
504
530
 
505
531
  ## What is not in here, deliberately
@@ -0,0 +1,130 @@
1
+ /**
2
+ * Folder writes, planned — RFC 0.4 §4, FOL-4.
3
+ *
4
+ * Every change to a Folder is one or more events published in order, and which
5
+ * events depends on one fact the relay will not check for you: **whether the
6
+ * Folder has a `kind:30890` yet.** `handle_folder_command` computes the next
7
+ * state from the existing one, and a Folder with no state has none — so any
8
+ * `kind:1852` against it emits state listing only what that command named, and
9
+ * everything filed in the Folder by `h` stops being listed on every surface
10
+ * (peek#192). Nothing fails; the Folder just looks emptied.
11
+ *
12
+ * That is why these are here rather than in each app. Peek learned it once per
13
+ * writer — rename, start a topic, delete a file — and its move never learned it
14
+ * at all. Ship is the second app to write Folder commands (ADR 0002 §10).
15
+ *
16
+ * ## Pure, and the caller says
17
+ *
18
+ * Each planner returns **unsigned** events and does nothing else: each app
19
+ * signs and publishes its own way. `hasState` is always an argument, never
20
+ * looked up, because the caller has just read the Folder and a guess here is
21
+ * silent loss. Nothing here reads the clock or makes an id — a new Folder's
22
+ * uuid is the caller's.
23
+ *
24
+ * ## Publish in order, and stop at the first refusal
25
+ *
26
+ * The array is the publish order and the order is the design: each later event
27
+ * assumes the earlier ones were accepted. What a refusal part-way through
28
+ * *means* — "created but not listed", "added but still in the old one" — is
29
+ * each app's to say, and the index of the refused event is enough to say it.
30
+ */
31
+ import { type ChannelVisibility, type UnsignedEvent } from '@estiva-app/protocol';
32
+ /** A Folder as a write needs it: which one, and whether the relay holds state for it. */
33
+ export interface FolderRef {
34
+ id: string;
35
+ /** `FolderSummary.hasState` / `FolderContents.hasState`, from a read — never a guess. */
36
+ hasState: boolean;
37
+ }
38
+ /**
39
+ * Create a Folder: `[kind:9007, kind:1852 add + name]`.
40
+ *
41
+ * The channel first, because a Folder *is* one (RFC 0.4 §4.1). Then a command
42
+ * naming it and listing nothing, so the Folder **has state from birth** — a
43
+ * listing that shows only Folders with state would otherwise never show it,
44
+ * and a stateless Folder is indistinguishable from a bare channel. Safe here
45
+ * and nowhere else without `hasState`: the channel was created by the first
46
+ * event, so nothing is filed in it to hide.
47
+ */
48
+ export declare function planCreateFolder(pubkey: string, createdAtMs: number, args: {
49
+ folder: string;
50
+ name: string;
51
+ visibility?: ChannelVisibility;
52
+ }): UnsignedEvent[];
53
+ /**
54
+ * Rename a Folder: `[kind:9002, kind:1852 add + name if it has state]`.
55
+ *
56
+ * **A Folder's name has two homes** and the state's shadows the channel's, so
57
+ * writing only the channel leaves the old name wherever the state is read. The
58
+ * command is `add` with no addresses — the contents are kept and only the name
59
+ * changes; `set` would empty it and there is no `rename` op. With no state
60
+ * there is only the channel to rename, and a command would empty the Folder.
61
+ */
62
+ export declare function planRenameFolder(pubkey: string, createdAtMs: number, args: {
63
+ folder: string;
64
+ name: string;
65
+ hasState: boolean;
66
+ }): UnsignedEvent[];
67
+ /**
68
+ * List a file that was just published into a Folder: `[kind:1852 add]` if the
69
+ * Folder has state, otherwise nothing.
70
+ *
71
+ * A Folder read by containment lists the file the moment its `h` is stored. A
72
+ * Folder with state lists only what its state names, so it needs the `add`.
73
+ * Publish the file first: a refused `add` then leaves a file that exists and
74
+ * is reachable, rather than a listing that points at nothing.
75
+ */
76
+ export declare function planPlaceFile(pubkey: string, createdAtMs: number, args: {
77
+ folder: string;
78
+ address: string;
79
+ hasState: boolean;
80
+ }): UnsignedEvent[];
81
+ /**
82
+ * Unlist a file that was just deleted from a Folder: `[kind:1852 remove]` if
83
+ * the Folder has state, otherwise nothing.
84
+ *
85
+ * {@link planPlaceFile} in reverse. A Folder with state lists what it names,
86
+ * deleted or not, so the row would stay pointing at nothing; a Folder read by
87
+ * containment stops listing the file once the relay hides it. Delete first: a
88
+ * refused `remove` then leaves a stale row, where the other order would unlist
89
+ * a file the relay kept.
90
+ */
91
+ export declare function planUnlistFile(pubkey: string, createdAtMs: number, args: {
92
+ folder: string;
93
+ address: string;
94
+ hasState: boolean;
95
+ }): UnsignedEvent[];
96
+ /**
97
+ * Why a move was refused. The source is checked first: no choice of target
98
+ * fixes it, so a consumer can stop offering Move for that file at all.
99
+ */
100
+ export type MoveRefusal = 'source-has-no-state' | 'target-has-no-state';
101
+ export type MovePlan = {
102
+ ok: true;
103
+ events: UnsignedEvent[];
104
+ } | {
105
+ ok: false;
106
+ reason: MoveRefusal;
107
+ };
108
+ /**
109
+ * Move a file between Folders: `[kind:1852 add to target, kind:1852 remove from source]`.
110
+ *
111
+ * **Add first.** There is no atomic move — state is per Folder — so something
112
+ * can fail between the two. After the add, a failure leaves the file in both
113
+ * Folders: visible, obviously wrong, fixed by moving again. Removing first and
114
+ * failing would leave it in neither, which looks like a file that never was.
115
+ *
116
+ * **Refused unless both Folders have state.** An `add` to a Folder with none
117
+ * emits state listing only the moved file, and everything already filed in it
118
+ * disappears; a `remove` from one emits state listing nothing, and the whole
119
+ * source disappears. Writing a complete state first is not offered here: what
120
+ * a stateless Folder holds is whatever its `h` implies to *this* reader, and a
121
+ * planner that enumerated it would be deciding on everyone's behalf.
122
+ *
123
+ * A move to the same Folder plans nothing.
124
+ */
125
+ export declare function planMoveFile(pubkey: string, createdAtMs: number, args: {
126
+ address: string;
127
+ from: FolderRef;
128
+ to: FolderRef;
129
+ }): MovePlan;
130
+ //# sourceMappingURL=folders.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"folders.d.ts","sourceRoot":"","sources":["../src/folders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAA;AAE7B,yFAAyF;AACzF,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,yFAAyF;IACzF,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,iBAAiB,CAAA;CAAE,GACrE,aAAa,EAAE,CASjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GACxD,aAAa,EAAE,CAIjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAC3D,aAAa,EAAE,CAGjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAC3D,aAAa,EAAE,CAGjB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,qBAAqB,GAAG,qBAAqB,CAAA;AAEvE,MAAM,MAAM,QAAQ,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,aAAa,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,CAAA;AAEjG;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,SAAS,CAAA;CAAE,GACxD,QAAQ,CAWV"}
@@ -0,0 +1,128 @@
1
+ /**
2
+ * Folder writes, planned — RFC 0.4 §4, FOL-4.
3
+ *
4
+ * Every change to a Folder is one or more events published in order, and which
5
+ * events depends on one fact the relay will not check for you: **whether the
6
+ * Folder has a `kind:30890` yet.** `handle_folder_command` computes the next
7
+ * state from the existing one, and a Folder with no state has none — so any
8
+ * `kind:1852` against it emits state listing only what that command named, and
9
+ * everything filed in the Folder by `h` stops being listed on every surface
10
+ * (peek#192). Nothing fails; the Folder just looks emptied.
11
+ *
12
+ * That is why these are here rather than in each app. Peek learned it once per
13
+ * writer — rename, start a topic, delete a file — and its move never learned it
14
+ * at all. Ship is the second app to write Folder commands (ADR 0002 §10).
15
+ *
16
+ * ## Pure, and the caller says
17
+ *
18
+ * Each planner returns **unsigned** events and does nothing else: each app
19
+ * signs and publishes its own way. `hasState` is always an argument, never
20
+ * looked up, because the caller has just read the Folder and a guess here is
21
+ * silent loss. Nothing here reads the clock or makes an id — a new Folder's
22
+ * uuid is the caller's.
23
+ *
24
+ * ## Publish in order, and stop at the first refusal
25
+ *
26
+ * The array is the publish order and the order is the design: each later event
27
+ * assumes the earlier ones were accepted. What a refusal part-way through
28
+ * *means* — "created but not listed", "added but still in the old one" — is
29
+ * each app's to say, and the index of the refused event is enough to say it.
30
+ */
31
+ import { buildCreateChannel, buildEditChannelMetadata, buildFolderCommand, } from '@estiva-app/protocol';
32
+ /**
33
+ * Create a Folder: `[kind:9007, kind:1852 add + name]`.
34
+ *
35
+ * The channel first, because a Folder *is* one (RFC 0.4 §4.1). Then a command
36
+ * naming it and listing nothing, so the Folder **has state from birth** — a
37
+ * listing that shows only Folders with state would otherwise never show it,
38
+ * and a stateless Folder is indistinguishable from a bare channel. Safe here
39
+ * and nowhere else without `hasState`: the channel was created by the first
40
+ * event, so nothing is filed in it to hide.
41
+ */
42
+ export function planCreateFolder(pubkey, createdAtMs, args) {
43
+ return [
44
+ buildCreateChannel(pubkey, createdAtMs, {
45
+ channelUuid: args.folder,
46
+ name: args.name,
47
+ ...(args.visibility ? { visibility: args.visibility } : {}),
48
+ }),
49
+ buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add', name: args.name }),
50
+ ];
51
+ }
52
+ /**
53
+ * Rename a Folder: `[kind:9002, kind:1852 add + name if it has state]`.
54
+ *
55
+ * **A Folder's name has two homes** and the state's shadows the channel's, so
56
+ * writing only the channel leaves the old name wherever the state is read. The
57
+ * command is `add` with no addresses — the contents are kept and only the name
58
+ * changes; `set` would empty it and there is no `rename` op. With no state
59
+ * there is only the channel to rename, and a command would empty the Folder.
60
+ */
61
+ export function planRenameFolder(pubkey, createdAtMs, args) {
62
+ const rename = buildEditChannelMetadata(pubkey, createdAtMs, { channelUuid: args.folder, name: args.name });
63
+ if (!args.hasState)
64
+ return [rename];
65
+ return [rename, buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add', name: args.name })];
66
+ }
67
+ /**
68
+ * List a file that was just published into a Folder: `[kind:1852 add]` if the
69
+ * Folder has state, otherwise nothing.
70
+ *
71
+ * A Folder read by containment lists the file the moment its `h` is stored. A
72
+ * Folder with state lists only what its state names, so it needs the `add`.
73
+ * Publish the file first: a refused `add` then leaves a file that exists and
74
+ * is reachable, rather than a listing that points at nothing.
75
+ */
76
+ export function planPlaceFile(pubkey, createdAtMs, args) {
77
+ if (!args.hasState)
78
+ return [];
79
+ return [buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add', addresses: [args.address] })];
80
+ }
81
+ /**
82
+ * Unlist a file that was just deleted from a Folder: `[kind:1852 remove]` if
83
+ * the Folder has state, otherwise nothing.
84
+ *
85
+ * {@link planPlaceFile} in reverse. A Folder with state lists what it names,
86
+ * deleted or not, so the row would stay pointing at nothing; a Folder read by
87
+ * containment stops listing the file once the relay hides it. Delete first: a
88
+ * refused `remove` then leaves a stale row, where the other order would unlist
89
+ * a file the relay kept.
90
+ */
91
+ export function planUnlistFile(pubkey, createdAtMs, args) {
92
+ if (!args.hasState)
93
+ return [];
94
+ return [buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'remove', addresses: [args.address] })];
95
+ }
96
+ /**
97
+ * Move a file between Folders: `[kind:1852 add to target, kind:1852 remove from source]`.
98
+ *
99
+ * **Add first.** There is no atomic move — state is per Folder — so something
100
+ * can fail between the two. After the add, a failure leaves the file in both
101
+ * Folders: visible, obviously wrong, fixed by moving again. Removing first and
102
+ * failing would leave it in neither, which looks like a file that never was.
103
+ *
104
+ * **Refused unless both Folders have state.** An `add` to a Folder with none
105
+ * emits state listing only the moved file, and everything already filed in it
106
+ * disappears; a `remove` from one emits state listing nothing, and the whole
107
+ * source disappears. Writing a complete state first is not offered here: what
108
+ * a stateless Folder holds is whatever its `h` implies to *this* reader, and a
109
+ * planner that enumerated it would be deciding on everyone's behalf.
110
+ *
111
+ * A move to the same Folder plans nothing.
112
+ */
113
+ export function planMoveFile(pubkey, createdAtMs, args) {
114
+ if (args.from.id === args.to.id)
115
+ return { ok: true, events: [] };
116
+ if (!args.from.hasState)
117
+ return { ok: false, reason: 'source-has-no-state' };
118
+ if (!args.to.hasState)
119
+ return { ok: false, reason: 'target-has-no-state' };
120
+ return {
121
+ ok: true,
122
+ events: [
123
+ buildFolderCommand(pubkey, createdAtMs, { folder: args.to.id, op: 'add', addresses: [args.address] }),
124
+ buildFolderCommand(pubkey, createdAtMs, { folder: args.from.id, op: 'remove', addresses: [args.address] }),
125
+ ],
126
+ };
127
+ }
128
+ //# sourceMappingURL=folders.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"folders.js","sourceRoot":"","sources":["../src/folders.ts"],"names":[],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -30,6 +30,12 @@ export { resolveManifest, resolveForeignObject, resolveForeignObjects, resolveFo
30
30
  * breadcrumbs and move targets, with cycles cut. No requests.
31
31
  */
32
32
  export { nestingOf, type Nestable, type Nesting } from './nesting.js';
33
+ /**
34
+ * Folder writes as unsigned events in publish order — create, rename, place,
35
+ * unlist, move. Each takes `hasState` from the caller, because a `kind:1852`
36
+ * against a Folder with no state empties it. No signing, no requests.
37
+ */
38
+ export { planCreateFolder, planRenameFolder, planPlaceFile, planUnlistFile, planMoveFile, type FolderRef, type MovePlan, type MoveRefusal, } from './folders.js';
33
39
  /**
34
40
  * RFC 0.5 §7's URL grammar — how an object is named in an address bar, and how
35
41
  * a pasted link is matched back to one.
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,0BAA0B,EAC1B,OAAO,EACP,KAAK,MAAM,EACX,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,KAAK,mBAAmB,EACxB,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,aAAa,EAClB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAA;AAExB;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,KAAK,OAAO,EAAE,MAAM,cAAc,CAAA;AAErE;;;;;;;GAOG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,0BAA0B,EAC1B,OAAO,EACP,KAAK,MAAM,EACX,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,KAAK,mBAAmB,EACxB,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,aAAa,EAClB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAA;AAExB;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,KAAK,OAAO,EAAE,MAAM,cAAc,CAAA;AAErE;;;;GAIG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,WAAW,GACjB,MAAM,cAAc,CAAA;AAErB;;;;;;;GAOG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAA"}
package/dist/index.js CHANGED
@@ -30,6 +30,12 @@ export { resolveManifest, resolveForeignObject, resolveForeignObjects, resolveFo
30
30
  * breadcrumbs and move targets, with cycles cut. No requests.
31
31
  */
32
32
  export { nestingOf } from './nesting.js';
33
+ /**
34
+ * Folder writes as unsigned events in publish order — create, rename, place,
35
+ * unlist, move. Each takes `hasState` from the caller, because a `kind:1852`
36
+ * against a Folder with no state empties it. No signing, no requests.
37
+ */
38
+ export { planCreateFolder, planRenameFolder, planPlaceFile, planUnlistFile, planMoveFile, } from './folders.js';
33
39
  /**
34
40
  * RFC 0.5 §7's URL grammar — how an object is named in an address bar, and how
35
41
  * a pasted link is matched back to one.
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,0BAA0B,EAC1B,OAAO,EAEP,cAAc,EACd,oBAAoB,EACpB,eAAe,EAEf,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAKhB,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EAErB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EAiBnB,cAAc,GAEf,MAAM,iBAAiB,CAAA;AAExB;;;GAGG;AACH,OAAO,EAAE,SAAS,EAA+B,MAAM,cAAc,CAAA;AAErE;;;;;;;GAOG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,GAGf,MAAM,gBAAgB,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,0BAA0B,EAC1B,OAAO,EAEP,cAAc,EACd,oBAAoB,EACpB,eAAe,EAEf,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAKhB,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EAErB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EAiBnB,cAAc,GAEf,MAAM,iBAAiB,CAAA;AAExB;;;GAGG;AACH,OAAO,EAAE,SAAS,EAA+B,MAAM,cAAc,CAAA;AAErE;;;;GAIG;AACH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,YAAY,GAIb,MAAM,cAAc,CAAA;AAErB;;;;;;;GAOG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,GAGf,MAAM,gBAAgB,CAAA"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.31.0",
3
+ "version": "0.32.0",
4
4
  "description": "Render and act on another app's objects from its published NIP-89 manifest. The owner defines the projection; the consumer decides how it looks.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -47,10 +47,10 @@
47
47
  "prepublishOnly": "npm run build"
48
48
  },
49
49
  "peerDependencies": {
50
- "@estiva-app/protocol": ">=0.9.0"
50
+ "@estiva-app/protocol": ">=0.23.0"
51
51
  },
52
52
  "devDependencies": {
53
- "@estiva-app/protocol": ">=0.9.0",
53
+ "@estiva-app/protocol": ">=0.23.0",
54
54
  "typescript": "~5.9.3"
55
55
  }
56
56
  }
package/src/folders.ts ADDED
@@ -0,0 +1,167 @@
1
+ /**
2
+ * Folder writes, planned — RFC 0.4 §4, FOL-4.
3
+ *
4
+ * Every change to a Folder is one or more events published in order, and which
5
+ * events depends on one fact the relay will not check for you: **whether the
6
+ * Folder has a `kind:30890` yet.** `handle_folder_command` computes the next
7
+ * state from the existing one, and a Folder with no state has none — so any
8
+ * `kind:1852` against it emits state listing only what that command named, and
9
+ * everything filed in the Folder by `h` stops being listed on every surface
10
+ * (peek#192). Nothing fails; the Folder just looks emptied.
11
+ *
12
+ * That is why these are here rather than in each app. Peek learned it once per
13
+ * writer — rename, start a topic, delete a file — and its move never learned it
14
+ * at all. Ship is the second app to write Folder commands (ADR 0002 §10).
15
+ *
16
+ * ## Pure, and the caller says
17
+ *
18
+ * Each planner returns **unsigned** events and does nothing else: each app
19
+ * signs and publishes its own way. `hasState` is always an argument, never
20
+ * looked up, because the caller has just read the Folder and a guess here is
21
+ * silent loss. Nothing here reads the clock or makes an id — a new Folder's
22
+ * uuid is the caller's.
23
+ *
24
+ * ## Publish in order, and stop at the first refusal
25
+ *
26
+ * The array is the publish order and the order is the design: each later event
27
+ * assumes the earlier ones were accepted. What a refusal part-way through
28
+ * *means* — "created but not listed", "added but still in the old one" — is
29
+ * each app's to say, and the index of the refused event is enough to say it.
30
+ */
31
+ import {
32
+ buildCreateChannel,
33
+ buildEditChannelMetadata,
34
+ buildFolderCommand,
35
+ type ChannelVisibility,
36
+ type UnsignedEvent,
37
+ } from '@estiva-app/protocol'
38
+
39
+ /** A Folder as a write needs it: which one, and whether the relay holds state for it. */
40
+ export interface FolderRef {
41
+ id: string
42
+ /** `FolderSummary.hasState` / `FolderContents.hasState`, from a read — never a guess. */
43
+ hasState: boolean
44
+ }
45
+
46
+ /**
47
+ * Create a Folder: `[kind:9007, kind:1852 add + name]`.
48
+ *
49
+ * The channel first, because a Folder *is* one (RFC 0.4 §4.1). Then a command
50
+ * naming it and listing nothing, so the Folder **has state from birth** — a
51
+ * listing that shows only Folders with state would otherwise never show it,
52
+ * and a stateless Folder is indistinguishable from a bare channel. Safe here
53
+ * and nowhere else without `hasState`: the channel was created by the first
54
+ * event, so nothing is filed in it to hide.
55
+ */
56
+ export function planCreateFolder(
57
+ pubkey: string,
58
+ createdAtMs: number,
59
+ args: { folder: string; name: string; visibility?: ChannelVisibility },
60
+ ): UnsignedEvent[] {
61
+ return [
62
+ buildCreateChannel(pubkey, createdAtMs, {
63
+ channelUuid: args.folder,
64
+ name: args.name,
65
+ ...(args.visibility ? { visibility: args.visibility } : {}),
66
+ }),
67
+ buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add', name: args.name }),
68
+ ]
69
+ }
70
+
71
+ /**
72
+ * Rename a Folder: `[kind:9002, kind:1852 add + name if it has state]`.
73
+ *
74
+ * **A Folder's name has two homes** and the state's shadows the channel's, so
75
+ * writing only the channel leaves the old name wherever the state is read. The
76
+ * command is `add` with no addresses — the contents are kept and only the name
77
+ * changes; `set` would empty it and there is no `rename` op. With no state
78
+ * there is only the channel to rename, and a command would empty the Folder.
79
+ */
80
+ export function planRenameFolder(
81
+ pubkey: string,
82
+ createdAtMs: number,
83
+ args: { folder: string; name: string; hasState: boolean },
84
+ ): UnsignedEvent[] {
85
+ const rename = buildEditChannelMetadata(pubkey, createdAtMs, { channelUuid: args.folder, name: args.name })
86
+ if (!args.hasState) return [rename]
87
+ return [rename, buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add', name: args.name })]
88
+ }
89
+
90
+ /**
91
+ * List a file that was just published into a Folder: `[kind:1852 add]` if the
92
+ * Folder has state, otherwise nothing.
93
+ *
94
+ * A Folder read by containment lists the file the moment its `h` is stored. A
95
+ * Folder with state lists only what its state names, so it needs the `add`.
96
+ * Publish the file first: a refused `add` then leaves a file that exists and
97
+ * is reachable, rather than a listing that points at nothing.
98
+ */
99
+ export function planPlaceFile(
100
+ pubkey: string,
101
+ createdAtMs: number,
102
+ args: { folder: string; address: string; hasState: boolean },
103
+ ): UnsignedEvent[] {
104
+ if (!args.hasState) return []
105
+ return [buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'add', addresses: [args.address] })]
106
+ }
107
+
108
+ /**
109
+ * Unlist a file that was just deleted from a Folder: `[kind:1852 remove]` if
110
+ * the Folder has state, otherwise nothing.
111
+ *
112
+ * {@link planPlaceFile} in reverse. A Folder with state lists what it names,
113
+ * deleted or not, so the row would stay pointing at nothing; a Folder read by
114
+ * containment stops listing the file once the relay hides it. Delete first: a
115
+ * refused `remove` then leaves a stale row, where the other order would unlist
116
+ * a file the relay kept.
117
+ */
118
+ export function planUnlistFile(
119
+ pubkey: string,
120
+ createdAtMs: number,
121
+ args: { folder: string; address: string; hasState: boolean },
122
+ ): UnsignedEvent[] {
123
+ if (!args.hasState) return []
124
+ return [buildFolderCommand(pubkey, createdAtMs, { folder: args.folder, op: 'remove', addresses: [args.address] })]
125
+ }
126
+
127
+ /**
128
+ * Why a move was refused. The source is checked first: no choice of target
129
+ * fixes it, so a consumer can stop offering Move for that file at all.
130
+ */
131
+ export type MoveRefusal = 'source-has-no-state' | 'target-has-no-state'
132
+
133
+ export type MovePlan = { ok: true; events: UnsignedEvent[] } | { ok: false; reason: MoveRefusal }
134
+
135
+ /**
136
+ * Move a file between Folders: `[kind:1852 add to target, kind:1852 remove from source]`.
137
+ *
138
+ * **Add first.** There is no atomic move — state is per Folder — so something
139
+ * can fail between the two. After the add, a failure leaves the file in both
140
+ * Folders: visible, obviously wrong, fixed by moving again. Removing first and
141
+ * failing would leave it in neither, which looks like a file that never was.
142
+ *
143
+ * **Refused unless both Folders have state.** An `add` to a Folder with none
144
+ * emits state listing only the moved file, and everything already filed in it
145
+ * disappears; a `remove` from one emits state listing nothing, and the whole
146
+ * source disappears. Writing a complete state first is not offered here: what
147
+ * a stateless Folder holds is whatever its `h` implies to *this* reader, and a
148
+ * planner that enumerated it would be deciding on everyone's behalf.
149
+ *
150
+ * A move to the same Folder plans nothing.
151
+ */
152
+ export function planMoveFile(
153
+ pubkey: string,
154
+ createdAtMs: number,
155
+ args: { address: string; from: FolderRef; to: FolderRef },
156
+ ): MovePlan {
157
+ if (args.from.id === args.to.id) return { ok: true, events: [] }
158
+ if (!args.from.hasState) return { ok: false, reason: 'source-has-no-state' }
159
+ if (!args.to.hasState) return { ok: false, reason: 'target-has-no-state' }
160
+ return {
161
+ ok: true,
162
+ events: [
163
+ buildFolderCommand(pubkey, createdAtMs, { folder: args.to.id, op: 'add', addresses: [args.address] }),
164
+ buildFolderCommand(pubkey, createdAtMs, { folder: args.from.id, op: 'remove', addresses: [args.address] }),
165
+ ],
166
+ }
167
+ }
package/src/index.ts CHANGED
@@ -93,6 +93,22 @@ export {
93
93
  */
94
94
  export { nestingOf, type Nestable, type Nesting } from './nesting.js'
95
95
 
96
+ /**
97
+ * Folder writes as unsigned events in publish order — create, rename, place,
98
+ * unlist, move. Each takes `hasState` from the caller, because a `kind:1852`
99
+ * against a Folder with no state empties it. No signing, no requests.
100
+ */
101
+ export {
102
+ planCreateFolder,
103
+ planRenameFolder,
104
+ planPlaceFile,
105
+ planUnlistFile,
106
+ planMoveFile,
107
+ type FolderRef,
108
+ type MovePlan,
109
+ type MoveRefusal,
110
+ } from './folders.js'
111
+
96
112
  /**
97
113
  * RFC 0.5 §7's URL grammar — how an object is named in an address bar, and how
98
114
  * a pasted link is matched back to one.