@estiva-app/interop 0.46.0 → 0.47.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.
@@ -719,7 +719,7 @@ function webTemplate(event, entity) {
719
719
  /**
720
720
  * The bare file — `kind:30840`, SPEC §6.7, decided in RFC 0.5 §10.7.
721
721
  *
722
- * A file **no app owns**: a `d`, a `title`, the `h` of the team it lives in, at
722
+ * A file **no app owns**: a `d`, a `title`, the `h` of the Folder it lives in, at
723
723
  * most one `a` naming the file it sits under, and a §13.3 block document (or
724
724
  * nothing) for content. A Peek topic is one. Typed kinds — a project, an issue
725
725
  * — add properties on top of this; the bare file adds none, which is exactly
@@ -845,7 +845,7 @@ const BARE_FILE_MANIFEST = {
845
845
 
846
846
  `rename` is a `kind:1851` change to the `title` field, not a re-publish of
847
847
  the `30840`. The title slot already folds `title`, so a rename by anyone in
848
- the team lands for every reader the way a re-parent does; a re-publish
848
+ the Folder lands for every reader the way a re-parent does; a re-publish
849
849
  could only ever be the author's, because a `30840` from another pubkey is a
850
850
  different address and not a refusal. `delete` is NIP-09's `kind:5` naming
851
851
  the address — the relay decides who may (the author, or the owner of an
@@ -856,7 +856,7 @@ const BARE_FILE_MANIFEST = {
856
856
  {
857
857
  id: 'comment',
858
858
  label: 'Comment',
859
- description: 'Say something about this file. The comment lands in the team Folder the file lives in, ' +
859
+ description: 'Say something about this file. The comment lands in the Folder the file lives in, ' +
860
860
  'and is what every reader of the file sees under it.',
861
861
  effect: 'writes',
862
862
  appliesTo: [String(KIND_BARE_FILE)],
@@ -866,7 +866,7 @@ const BARE_FILE_MANIFEST = {
866
866
  {
867
867
  id: 'rename',
868
868
  label: 'Rename',
869
- description: 'Give this file a new title. A change event, so anyone in the team may, and every app ' +
869
+ description: 'Give this file a new title. A change event, so anyone in the Folder may, and every app ' +
870
870
  'reading the file folds it into the title.',
871
871
  effect: 'writes',
872
872
  appliesTo: [String(KIND_BARE_FILE)],
@@ -876,15 +876,15 @@ const BARE_FILE_MANIFEST = {
876
876
  /*
877
877
  `move` is the `parent` field SPEC §6.7 already defines, declared so a
878
878
  consumer draws the control from here as it draws Rename (FOL-4). The value
879
- is the new parent's address, or empty for the top of the team. A move
879
+ is the new parent's address, or empty for the top of the Folder. A move
880
880
  never changes `h`: nesting organises and never grants access, so a file
881
- moved under another stays readable by exactly the team it was.
881
+ moved under another stays readable by exactly the people it was.
882
882
  */
883
883
  {
884
884
  id: 'move',
885
885
  label: 'Move',
886
- description: "Put this file under another file in the same team, or back at the top. A change event, so anyone in " +
887
- 'the team may; who can read the file does not change.',
886
+ description: "Put this file under another file in the same Folder, or back at the top. A change event, so anyone in " +
887
+ 'the Folder may; who can read the file does not change.',
888
888
  effect: 'writes',
889
889
  appliesTo: [String(KIND_BARE_FILE)],
890
890
  emits: { kind: 1851, field: 'parent' },
@@ -893,7 +893,7 @@ const BARE_FILE_MANIFEST = {
893
893
  /*
894
894
  `archive` is the one field every file may carry (FOL-46): `true` hides the
895
895
  file and everything under it from every list, an empty value brings it
896
- back. A change, so anyone in the team may, and the archiving change's
896
+ back. A change, so anyone in the Folder may, and the archiving change's
897
897
  `content` is the resolution summary a person gave (`ActionEventArgs.note`).
898
898
  */
899
899
  {
@@ -1437,8 +1437,20 @@ export function isArchived(file) {
1437
1437
  * `changes` may hold any events; only this rule's change kind, naming this
1438
1438
  * address, setting this field, is read. Last write wins, by the same order as
1439
1439
  * every other field.
1440
+ *
1441
+ * **A Folder is the exception** (SPEC §3.2): on a `kind:39000` address only a
1442
+ * change in the Folder's own `h` by one of `folderAdmins` — the owners and
1443
+ * admins on its relay-signed `kind:39001` — counts. A caller that has not read
1444
+ * the admin list passes none, and then no change counts: a Folder shown live
1445
+ * when it is archived is recoverable, one any member could hide is not.
1440
1446
  */
1441
- function archiveOf(changes, address, rule) {
1447
+ function archiveOf(changes, address, rule, folderAdmins) {
1448
+ const [kind, , folderId] = address.split(':');
1449
+ if (Number(kind) === KIND_CHANNEL) {
1450
+ if (!folderAdmins?.size)
1451
+ return undefined;
1452
+ changes = changes.filter((change) => tagValue(change, 'h') === folderId && folderAdmins.has(change.pubkey));
1453
+ }
1442
1454
  let last;
1443
1455
  for (const change of changes) {
1444
1456
  // The target is the first target tag, as every other fold reads it: a
@@ -3977,13 +3989,39 @@ export const KIND_FOLDER_STATE = 30890;
3977
3989
  /**
3978
3990
  * NIP-29 group metadata — the Folder's channel.
3979
3991
  *
3980
- * Named here for two unrelated jobs: it carries the folder's `name` before any
3981
- * folder state exists, and its own address is what makes a Peek topic a file
3982
- * like any other (§5.2).
3992
+ * Named here for two unrelated jobs: it carries the Folder's title — its
3993
+ * `name`, and only that (SPEC §3.2) — and its own address is what makes a Peek
3994
+ * topic a file like any other (§5.2).
3983
3995
  */
3984
3996
  const KIND_CHANNEL = 39000;
3997
+ /** NIP-29 group admins — the relay's list of who holds which role in a channel. */
3998
+ const KIND_CHANNEL_ADMINS = 39001;
3999
+ /** The roles on a `kind:39001` that may rename a Folder, and so archive it (SPEC §3.2). */
4000
+ const FOLDER_ADMIN_ROLES = new Set(['owner', 'admin']);
3985
4001
  /** The `name` tag, when there is an event to read it off at all. */
3986
4002
  const nameOf = (event) => (event ? tagValue(event, 'name') : undefined);
4003
+ /**
4004
+ * The owners and admins a `kind:39001` lists — kept only when the channel's own
4005
+ * signer, the relay, signed it: anybody can publish an event of that shape.
4006
+ */
4007
+ function folderAdminsOf(admins, channel) {
4008
+ if (!admins || !channel || admins.pubkey !== channel.pubkey)
4009
+ return [];
4010
+ return [
4011
+ ...new Set(admins.tags
4012
+ .filter((tag) => tag[0] === 'p' && tag[1] && tag.slice(2).some((role) => FOLDER_ADMIN_ROLES.has(role)))
4013
+ .map((tag) => tag[1])),
4014
+ ];
4015
+ }
4016
+ /**
4017
+ * A Folder's own archive (SPEC §3.2): the `archived` changes on its channel's
4018
+ * address, counting only one carrying the Folder's own `h` whose author the
4019
+ * relay lists as its owner or admin. From anybody else the relay accepts the
4020
+ * change, and it means nothing.
4021
+ */
4022
+ function folderArchiveOf(changes, folder) {
4023
+ return folder.channel ? archiveOf(changes, folder.channel, ARCHIVE_RULE, new Set(folder.admins ?? [])) : undefined;
4024
+ }
3987
4025
  /**
3988
4026
  * The folders a person navigates by: the ones with state that no other folder
3989
4027
  * lists (FOL-5).
@@ -3996,7 +4034,7 @@ const nameOf = (event) => (event ? tagValue(event, 'name') : undefined);
3996
4034
  * never gets; and a folder another one lists (`listedIn`) is a row inside
3997
4035
  * that one, not a section beside it.
3998
4036
  *
3999
- * Not a list of ids: a new team is a folder somebody creates, not a code
4037
+ * Not a list of ids: a new Folder is a folder somebody creates, not a code
4000
4038
  * change. Moved here from Peek and Ship, which each held the same line.
4001
4039
  *
4002
4040
  * An archived Folder is not navigated by (FOL-46), and a listing that has not
@@ -4009,8 +4047,8 @@ export function topLevelFolders(folders) {
4009
4047
  * Every folder this identity can see, for a sidebar.
4010
4048
  *
4011
4049
  * Both shapes in one pass: folders the relay maintains state for, and bare
4012
- * channels that have none yet. A channel with state appears once, named by its
4013
- * state — the folder's name is the folder's to say.
4050
+ * channels that have none yet. A channel with state appears once, titled by its
4051
+ * `kind:39000` (SPEC §3.2), with the owners and admins its `kind:39001` lists.
4014
4052
  *
4015
4053
  * **A direct route, deliberately.** §4.2's post-mortem on REW-11 is that
4016
4054
  * discovering children only through their parent loses them when the parent
@@ -4021,30 +4059,44 @@ export async function listFolders(query) {
4021
4059
  const events = await query([
4022
4060
  { kinds: [KIND_FOLDER_STATE], limit: 500 },
4023
4061
  { kinds: [KIND_CHANNEL], limit: 500 },
4062
+ { kinds: [KIND_CHANNEL_ADMINS], limit: 500 },
4024
4063
  ]);
4025
4064
  const byId = new Map();
4065
+ const channelOf = new Map();
4066
+ const adminsOf = new Map();
4026
4067
  for (const event of events) {
4027
4068
  const id = tagValue(event, 'd');
4028
4069
  if (!id)
4029
4070
  continue;
4071
+ if (event.kind === KIND_CHANNEL)
4072
+ channelOf.set(id, event);
4073
+ if (event.kind === KIND_CHANNEL_ADMINS)
4074
+ adminsOf.set(id, event);
4075
+ if (event.kind !== KIND_FOLDER_STATE && event.kind !== KIND_CHANNEL)
4076
+ continue;
4030
4077
  const state = event.kind === KIND_FOLDER_STATE;
4031
4078
  const existing = byId.get(id);
4032
- // State wins over the channel for the name, whichever order they arrived.
4033
- if (existing && !state)
4034
- continue;
4035
- const addresses = state ? event.tags.filter((tag) => tag[0] === 'a' && tag[1]).map((tag) => tag[1]) : [];
4079
+ const addresses = state ? event.tags.filter((tag) => tag[0] === 'a' && tag[1]).map((tag) => tag[1]) : (existing?.addresses ?? []);
4036
4080
  byId.set(id, {
4037
4081
  id,
4038
- name: tagValue(event, 'name') ?? existing?.name,
4039
4082
  hasState: state || (existing?.hasState ?? false),
4040
4083
  ...(addresses.length ? { addresses } : {}),
4041
4084
  });
4042
4085
  }
4043
- for (const event of events) {
4044
- const id = tagValue(event, 'd');
4045
- const folder = id && event.kind === KIND_CHANNEL ? byId.get(id) : undefined;
4046
- if (folder)
4047
- folder.channel = pointerToAddress({ kind: KIND_CHANNEL, pubkey: event.pubkey, identifier: id, relays: [] });
4086
+ // The title, privacy and admins are the channel's (§3.2), whichever order the events arrived.
4087
+ for (const [id, folder] of byId) {
4088
+ const channel = channelOf.get(id);
4089
+ if (!channel)
4090
+ continue;
4091
+ const name = nameOf(channel);
4092
+ if (name !== undefined)
4093
+ folder.name = name;
4094
+ if (channel.tags.some((tag) => tag[0] === 'private'))
4095
+ folder.private = true;
4096
+ const admins = folderAdminsOf(adminsOf.get(id), channel);
4097
+ if (admins.length)
4098
+ folder.admins = admins;
4099
+ folder.channel = pointerToAddress({ kind: KIND_CHANNEL, pubkey: channel.pubkey, identifier: id, relays: [] });
4048
4100
  }
4049
4101
  /*
4050
4102
  A folder listed in another folder's state is a file there. Read off the
@@ -4086,18 +4138,18 @@ export async function listFolders(query) {
4086
4138
  *
4087
4139
  * A Folder is archived by a change naming its channel's address, the way any
4088
4140
  * file is. A record's channel — a Ship project's conversation — is archived
4089
- * with its record, so an archived project's channel stops lighting its team's
4141
+ * with its record, so an archived project's channel stops lighting its Folder's
4090
4142
  * dot the way the project stopped being listed — only when every record naming
4091
4143
  * the channel is archived, since two projects may share one. Its own archive
4092
4144
  * wins when it has one.
4093
4145
  *
4094
4146
  * A refused read throws before this, like the reads beside it: a listing that
4095
- * silently reported every Folder live would put archived teams back in
4147
+ * silently reported every Folder live would put archived Folders back in
4096
4148
  * everyone's sidebar.
4097
4149
  */
4098
4150
  function markArchivedFolders(byId, recordsOf, changes) {
4099
4151
  for (const folder of byId.values()) {
4100
- const own = folder.channel ? archiveOf(changes, folder.channel, ARCHIVE_RULE) : undefined;
4152
+ const own = folderArchiveOf(changes, folder);
4101
4153
  if (own) {
4102
4154
  folder.archived = own;
4103
4155
  continue;
@@ -4247,13 +4299,13 @@ async function countLiveChildren(parents, counted, query, cache) {
4247
4299
  * names the channel its conversation lives in with {@link folderOf}'s tags. No
4248
4300
  * state lists that channel, so without this `listFolders` reports it placed
4249
4301
  * nowhere, and a consumer folding an unread verdict into the containers of a
4250
- * channel (Peek's team dot) has nowhere to fold it: correct, and drawn
4302
+ * channel (Peek's Folder dot) has nowhere to fold it: correct, and drawn
4251
4303
  * nowhere. Measured on production 2026-09-22: of the 43 records the six
4252
4304
  * states list, 23 name a channel other than the state's own and no state lists
4253
4305
  * any of them. This places 21 channels and moves no top-level Folder.
4254
4306
  *
4255
4307
  * Derived rather than published, so it cannot drift: a `kind:1852` adding each
4256
- * channel to its team would have to be repeated by every app that places a
4308
+ * channel to its Folder would have to be repeated by every app that places a
4257
4309
  * record, and would stay wrong the first time one did not.
4258
4310
  *
4259
4311
  * Both of `folderOf`'s spellings, because production has both — about half of
@@ -4278,7 +4330,7 @@ async function countLiveChildren(parents, counted, query, cache) {
4278
4330
  * production that was the bug it was meant to prevent: Peek reads the listing
4279
4331
  * once per page load, the load is when the relay's budget is most contested,
4280
4332
  * and one refused read on 2026-09-22 left a project's channel unplaced for the
4281
- * whole session — the team's dot dark, and nothing anywhere saying why. A
4333
+ * whole session — the Folder's dot dark, and nothing anywhere saying why. A
4282
4334
  * listing missing placements looks exactly like a correct one, so only the
4283
4335
  * caller can recover, and only if it is told. Keeping the last good listing
4284
4336
  * and retrying is the caller's to do.
@@ -4359,7 +4411,7 @@ async function placeRecordChannels(events, byId, listedIn, query) {
4359
4411
  if (!channel || byId.get(channel)?.hasState)
4360
4412
  continue;
4361
4413
  // A file published into the Folder that lists it names that Folder, and
4362
- // does not own it: a topic's `h` is its team's.
4414
+ // does not own it: a topic's `h` is its Folder's.
4363
4415
  if (!containers.includes(channel))
4364
4416
  recordsOf.set(channel, [...(recordsOf.get(channel) ?? []), key]);
4365
4417
  for (const container of containers) {
@@ -4426,16 +4478,20 @@ cache, options = {}) {
4426
4478
  const identity = await query([
4427
4479
  { kinds: [KIND_FOLDER_STATE], '#d': [folder], limit: 1 },
4428
4480
  { kinds: [KIND_CHANNEL], '#d': [folder], limit: 1 },
4481
+ { kinds: [KIND_CHANNEL_ADMINS], '#d': [folder], limit: 1 },
4429
4482
  ]);
4430
4483
  const state = identity.find((e) => e.kind === KIND_FOLDER_STATE && tagValue(e, 'd') === folder);
4431
4484
  const channel = identity.find((e) => e.kind === KIND_CHANNEL && tagValue(e, 'd') === folder);
4485
+ const admins = folderAdminsOf(identity.find((e) => e.kind === KIND_CHANNEL_ADMINS && tagValue(e, 'd') === folder), channel);
4432
4486
  const channelAddress = channel
4433
4487
  ? pointerToAddress({ kind: KIND_CHANNEL, pubkey: channel.pubkey, identifier: folder, relays: [] })
4434
4488
  : undefined;
4435
4489
  const summary = {
4436
4490
  id: folder,
4437
- name: nameOf(state) ?? nameOf(channel),
4491
+ name: nameOf(channel),
4438
4492
  hasState: !!state,
4493
+ ...(channel?.tags.some((tag) => tag[0] === 'private') ? { private: true } : {}),
4494
+ ...(admins.length ? { admins } : {}),
4439
4495
  ...(channelAddress ? { channel: channelAddress } : {}),
4440
4496
  ...(state
4441
4497
  ? { address: pointerToAddress({ kind: state.kind, pubkey: state.pubkey, identifier: folder, relays: [] }) }
@@ -4452,9 +4508,7 @@ cache, options = {}) {
4452
4508
  if (addresses.length === 0) {
4453
4509
  // Nothing listed, so no change query to ride on: the Folder's own archive
4454
4510
  // is one small read of its own.
4455
- const archived = channelAddress
4456
- ? archiveOf(await readArchiveChanges([channelAddress], query), channelAddress, ARCHIVE_RULE)
4457
- : undefined;
4511
+ const archived = channelAddress ? folderArchiveOf(await readArchiveChanges([channelAddress], query), summary) : undefined;
4458
4512
  return { ...summary, ...(archived ? { archived } : {}), files: [], source: state ? 'state' : 'channel' };
4459
4513
  }
4460
4514
  // 2. Group by (kind, author): one manifest answers for every file an app owns
@@ -4504,6 +4558,7 @@ cache, options = {}) {
4504
4558
  ...[...manifests.values()].flatMap((r) => (r.manifest.records ? [r.manifest.records.changeKind] : [])),
4505
4559
  ]),
4506
4560
  ];
4561
+ const nestedFolderIds = pointers.filter(({ pointer }) => pointer.kind === KIND_CHANNEL).map(({ pointer }) => pointer.identifier);
4507
4562
  const events = await query([
4508
4563
  ...[...groups.values()].map(({ pointer, addresses: group }) => ({
4509
4564
  kinds: [pointer.kind],
@@ -4517,8 +4572,10 @@ cache, options = {}) {
4517
4572
  // changes for every file together, and one Folder has already had 688.
4518
4573
  // Same request.
4519
4574
  ...archiveFilters(channelAddress ? [...addresses, channelAddress] : addresses),
4575
+ // A Folder listed here counts its archive only from its own admins (§3.2). Same request.
4576
+ ...(nestedFolderIds.length ? [{ kinds: [KIND_CHANNEL_ADMINS], '#d': nestedFolderIds, limit: nestedFolderIds.length }] : []),
4520
4577
  ]);
4521
- const ownArchive = channelAddress ? archiveOf(events, channelAddress, ARCHIVE_RULE) : undefined;
4578
+ const ownArchive = folderArchiveOf(events, summary);
4522
4579
  if (ownArchive)
4523
4580
  summary.archived = ownArchive;
4524
4581
  // 4. Build each file, in the order the folder listed them. Archived files are
@@ -4542,7 +4599,10 @@ cache, options = {}) {
4542
4599
  continue;
4543
4600
  const records = foldRuleOf(resolved.manifest);
4544
4601
  const folded = foldChanges(events.filter((e) => e.kind === records.changeKind && hasTagValue(e, records.targetTag, address)), records);
4545
- const archive = archiveOf(events, address, archiveRuleOf(resolved.manifest));
4602
+ const nestedAdmins = pointer.kind === KIND_CHANNEL
4603
+ ? new Set(folderAdminsOf(events.find((e) => e.kind === KIND_CHANNEL_ADMINS && tagValue(e, 'd') === pointer.identifier), root))
4604
+ : undefined;
4605
+ const archive = archiveOf(events, address, archiveRuleOf(resolved.manifest), nestedAdmins);
4546
4606
  archiveByAddress.set(address, archive);
4547
4607
  const parent = parentRefOf(resolved.manifest, pointer.kind, root, folded);
4548
4608
  parentByAddress.set(address, parent);
@@ -4564,7 +4624,7 @@ cache, options = {}) {
4564
4624
  the file is here; if the fold has moved on, somebody has since placed it
4565
4625
  somewhere else and this folder is holding a statement that has been
4566
4626
  superseded, which an append-only stream cannot retract. Ship linking a
4567
- project to a second team is the case: the first team's Folder keeps the
4627
+ project to a second Folder is the case: the first Folder keeps the
4568
4628
  old statement for ever, and without this check would list the project
4569
4629
  for ever.
4570
4630
 
@@ -4662,17 +4722,17 @@ cache, options = {}) {
4662
4722
  *
4663
4723
  * A folder lists the files whose `h` it is **and** the files placed in it.
4664
4724
  * An event cannot change its own `h`, so a project filed in one Folder and
4665
- * later linked to a team keeps the `h` it was born with, and the only thing
4725
+ * later linked to a Folder keeps the `h` it was born with, and the only thing
4666
4726
  * that can say "it belongs over there now" is a change event. Ship publishes
4667
4727
  * that change twice — into the record's own Folder, and *into the Folder
4668
- * being linked*: a `kind:1851` carried by the team's `h`, targeting the
4669
- * project, whose value is the team Folder itself. The second copy is the
4728
+ * being linked*: a `kind:1851` carried by the Folder's `h`, targeting the
4729
+ * project, whose value is the Folder itself. The second copy is the
4670
4730
  * placement, and it is what this reads.
4671
4731
  *
4672
4732
  * {@link resolveFolderProject} has read the same statement since PEEK-24 to
4673
4733
  * answer "which project is this topic paired with". This is the listing's
4674
- * half of it, and it is the rule the tidy-up rests on: five team Folders,
4675
- * fourteen projects linked into them and none re-created, so a team Folder
4734
+ * half of it, and it is the rule the tidy-up rests on: five Folders,
4735
+ * fourteen projects linked into them and none re-created, so a Folder
4676
4736
  * whose `h` is on nothing lists its projects anyway.
4677
4737
  *
4678
4738
  * App-neutral by the same discipline as everything else here. The change