@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 +23 -0
- package/README.md +26 -0
- package/dist/folders.d.ts +130 -0
- package/dist/folders.d.ts.map +1 -0
- package/dist/folders.js +128 -0
- package/dist/folders.js.map +1 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -0
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
- package/src/folders.ts +167 -0
- package/src/index.ts +16 -0
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"}
|
package/dist/folders.js
ADDED
|
@@ -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.
|
package/dist/index.d.ts.map
CHANGED
|
@@ -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.
|
|
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.
|
|
50
|
+
"@estiva-app/protocol": ">=0.23.0"
|
|
51
51
|
},
|
|
52
52
|
"devDependencies": {
|
|
53
|
-
"@estiva-app/protocol": ">=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.
|