@estiva-app/interop 0.97.0 → 0.99.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.97.0",
3
+ "version": "0.99.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",
package/src/folders.ts CHANGED
@@ -117,8 +117,8 @@ export function planCreateFolder(
117
117
  * Rename a Folder: `[kind:9002]`, and nothing else.
118
118
  *
119
119
  * The title is the channel's name (§3.2), so the channel is the only home to
120
- * write. The relay refuses it to anybody but the channel's owners and admins.
121
- * A name left on an older state by a command is never shown.
120
+ * write. The relay refuses it to anybody but the channel's owners and admins
121
+ * (and, on a team with no owner, the workspace's). A name left on an older state by a command is never shown.
122
122
  */
123
123
  export function planRenameFolder(
124
124
  pubkey: string,
@@ -221,8 +221,9 @@ export function planUnlistFile(
221
221
  * unlist a file from somewhere a person would have to remember.
222
222
  *
223
223
  * **Always in the Folder's own `h`**, and readers count it only from an owner
224
- * or admin on the Folder's `kind:39001` (§3.2) — the people who may rename it.
225
- * So offer Archive only to them (`FolderSummary.admins`): from anybody else the
224
+ * or admin on the Folder's `kind:39001` — or, on a team with no owner, from an
225
+ * owner or admin of the workspace (§3.2) — the people who may rename it. So
226
+ * offer Archive only to them (`FolderSummary.admins`): from anybody else the
226
227
  * relay accepts the event and every reader ignores it.
227
228
  *
228
229
  * `resolution` is what the person archiving said about it, carried as the
package/src/projection.ts CHANGED
@@ -2521,7 +2521,8 @@ export function isArchived(file: { archived?: Archive } | null | undefined): boo
2521
2521
  *
2522
2522
  * **A Folder is the exception** (SPEC §3.2): on a `kind:39000` address only a
2523
2523
  * change in the Folder's own `h` by one of `folderAdmins` — the owners and
2524
- * admins on its relay-signed `kind:39001` — counts. A caller that has not read
2524
+ * admins on its relay-signed `kind:39001`, and on a team with no owner the
2525
+ * workspace's owners and admins — counts. A caller that has not read
2525
2526
  * the admin list passes none, and then no change counts: a Folder shown live
2526
2527
  * when it is archived is recoverable, one any member could hide is not.
2527
2528
  */
@@ -3357,6 +3358,12 @@ export interface ForeignObject {
3357
3358
  * `created_at`. Absent on an unreachable stub, which has no root to read.
3358
3359
  */
3359
3360
  changedAt?: number
3361
+ /**
3362
+ * Who made the change {@link changedAt} names, as a pubkey: the author of the
3363
+ * newest folded field's winning change, or the root's when no change is newer
3364
+ * than it. For "edited by … , 2h ago" on a row. Absent where `changedAt` is.
3365
+ */
3366
+ changedBy?: string
3360
3367
  /**
3361
3368
  * Each changed field's current change id: the `prev` a change to that field
3362
3369
  * names (SPEC §6.2). A field never changed is absent, and its first change
@@ -3391,6 +3398,13 @@ function changedAtOf(root: SignedEvent, folded: Record<string, { at?: number }>)
3391
3398
  return Math.max(root.created_at, ...Object.values(folded).map((f) => f.at ?? 0))
3392
3399
  }
3393
3400
 
3401
+ /** Who made the newest of a root and its folded fields' changes: the root's author on a tie, as nothing changed it after. */
3402
+ function changedByOf(root: SignedEvent, folded: Record<string, { at?: number; by?: string }>): string {
3403
+ let newest = { at: root.created_at, by: root.pubkey }
3404
+ for (const f of Object.values(folded)) if (f.by && (f.at ?? 0) > newest.at) newest = { at: f.at!, by: f.by }
3405
+ return newest.by
3406
+ }
3407
+
3394
3408
 
3395
3409
  /**
3396
3410
  * One resolved object, from its root event and the changes that have landed on
@@ -3442,6 +3456,7 @@ function buildObject(args: {
3442
3456
  viaRecommendation: args.viaRecommendation,
3443
3457
  ...(args.archived ? { archived: args.archived } : {}),
3444
3458
  changedAt: changedAtOf(root, folded),
3459
+ changedBy: changedByOf(root, folded),
3445
3460
  ...(Object.keys(prevs).length ? { prevs } : {}),
3446
3461
  ...(deleted?.value === 'true' && deleted.by ? { deleted: { by: deleted.by, at: deleted.at ?? root.created_at } } : {}),
3447
3462
  }
@@ -3912,8 +3927,13 @@ export async function resolveForeignRoots(
3912
3927
  * deleted file is absent. Other kinds are read as before.
3913
3928
  * `parentsListRead`, with `archivedWith`, reads only the parents walked for an archive by the list read (with
3914
3929
  * `listRead`'s fallback for one it leaves out); the files asked for are still read in full, their text included.
3930
+ * `children`, with `listRead`, also gives each listed file whose app declares a list of files the files under it,
3931
+ * one level down, folded as {@link resolveForeignObjects}' are: by the same list read, so a child's text is never
3932
+ * read, and a child moved in (§7.2) found by its move. Archived children are dropped, and a child carries no
3933
+ * actions. A list of other kinds (a topic's messages) is not read, and its `children` stay absent. Without
3934
+ * `listRead` it asks nothing more.
3915
3935
  */
3916
- options: Pick<ArchiveReadOptions, 'archivedWith'> & { listRead?: boolean; parentsListRead?: boolean } = {},
3936
+ options: Pick<ArchiveReadOptions, 'archivedWith'> & { listRead?: boolean; parentsListRead?: boolean; children?: boolean } = {},
3917
3937
  ): Promise<ForeignObject[]> {
3918
3938
  const pointers = new Map<string, AddressPointer>()
3919
3939
  for (const reference of references) {
@@ -3940,10 +3960,43 @@ export async function resolveForeignRoots(
3940
3960
  filters.push(root, { kinds: [...changeKinds], '#a': [address], limit: 500 })
3941
3961
  }
3942
3962
  const listed = listReadFilters(listedPointers)
3963
+ // The children's first records ride in the list read (TOPI-8). The moves naming a parent are asked on their own:
3964
+ // every move that ever named it comes back, stale ones too, so they only say which children to read and are never
3965
+ // folded — a child's place is its list read's current change, in the relay's order (§6.13).
3966
+ const lists = options.children ? childListsOf(listedPointers, manifests) : []
3967
+ const moves: Record<string, unknown>[] = []
3968
+ for (const { childFilter } of lists) {
3969
+ listed.push({ ...childFilter.filter, fields: 'newest' })
3970
+ if (childFilter.movedIn) moves.push(childFilter.movedIn)
3971
+ }
3943
3972
  if (filters.length === 0 && listed.length === 0) return []
3944
3973
  // A relay refuses a request mixing list reads with plain ones, so each goes on its own.
3945
- const events = (await Promise.all([queryChunked(filters, query), queryChunked(listed, query)])).flat()
3946
- const projected = projectEvents(events, (pointer) => manifests.get(manifestKeyOf(pointer)))
3974
+ const [plain, answered, named] = await Promise.all([queryChunked(filters, query), queryChunked(listed, query), queryChunked(moves, query)])
3975
+ const events = [...plain, ...answered]
3976
+ // A child moved in is named only by its move, so its own first record is read once those are back.
3977
+ const held = new Set(answered.flatMap((e) => childAddressOf(e) ?? []))
3978
+ const movedIn = lists.flatMap(({ childFilter, resolved }) =>
3979
+ movedInAddressesOf(named, childFilter, resolved.manifest.records).filter((address) => !held.has(address)),
3980
+ )
3981
+ const moved = movedIn.flatMap((address) => addressPointerOf(address) ?? [])
3982
+ const childEvents = [...answered, ...(moved.length ? await queryChunked(listReadFilters(moved), query) : [])]
3983
+ const all = projectEvents(events, (pointer) => manifests.get(manifestKeyOf(pointer)))
3984
+ // The children's own first records came back too; only the files asked for are answers.
3985
+ const projected = lists.length ? all.filter((object) => !!object.address && pointers.has(object.address)) : all
3986
+ for (const { childFilter, resolved, address } of lists) {
3987
+ const parent = projected.find((object) => object.address === address)
3988
+ if (!parent) continue
3989
+ const children = childrenFrom({
3990
+ // The moves only find who moved in; each child folds from its list read alone.
3991
+ events: [...answered, ...named],
3992
+ childFilter,
3993
+ manifest: resolved.manifest,
3994
+ webTemplate: resolved.webTemplate,
3995
+ viaRecommendation: resolved.viaRecommendation,
3996
+ childChanges: childEvents,
3997
+ })
3998
+ if (children) parent.children = textUnread(children)
3999
+ }
3947
4000
  const objects = options.listRead ? textUnread(projected) : projected
3948
4001
  if (options.archivedWith) {
3949
4002
  const manifestOf = (object: ForeignObject) => {
@@ -3960,6 +4013,21 @@ export async function resolveForeignRoots(
3960
4013
  return objects
3961
4014
  }
3962
4015
 
4016
+ /** The child list each listed file's app declares, for {@link resolveForeignRoots}' `children`: files of the list read only. */
4017
+ function childListsOf(
4018
+ pointers: readonly AddressPointer[],
4019
+ manifests: Map<string, ResolvedManifest>,
4020
+ ): { address: string; resolved: ResolvedManifest; childFilter: NonNullable<ReturnType<typeof childFilterFor>> }[] {
4021
+ return pointers.flatMap((pointer) => {
4022
+ const resolved = manifests.get(manifestKeyOf(pointer))
4023
+ const projection = resolved?.manifest.projections?.[String(pointer.kind)]
4024
+ if (!resolved || !projection) return []
4025
+ const childFilter = childFilterFor({ projection, manifest: resolved.manifest, pointer, depth: 0 })
4026
+ if (!childFilter || !FILE_KINDS.includes(childFilter.kind)) return []
4027
+ return [{ address: `${pointer.kind}:${pointer.pubkey}:${pointer.identifier}`, resolved, childFilter }]
4028
+ })
4029
+ }
4030
+
3963
4031
  /**
3964
4032
  * Topics as their roots and changes draw them, through the bare file's
3965
4033
  * built-in manifest (§6.7) — what {@link resolveForeignRoots} draws a topic
@@ -5394,6 +5462,7 @@ function buildChildObject(args: {
5394
5462
  actions: addressable && !nevent && ownsKind ? actionsOfFile(manifest, projection, root, folded) : [],
5395
5463
  viaRecommendation,
5396
5464
  changedAt: changedAtOf(root, folded),
5465
+ changedBy: changedByOf(root, folded),
5397
5466
  ...(archived ? { archived } : {}),
5398
5467
  }
5399
5468
  }
@@ -6678,10 +6747,55 @@ function folderAdminsOf(admins: SignedEvent | undefined, channel: SignedEvent |
6678
6747
  ]
6679
6748
  }
6680
6749
 
6750
+ /** NIP-43's relay membership list: the workspace's roster, one `member` tag per key, with its role. */
6751
+ const KIND_RELAY_MEMBERS = 13534
6752
+
6753
+ /** The relay's roster, as a filter to add to a request that already reads a team's records. */
6754
+ const RELAY_MEMBERS_FILTER = { kinds: [KIND_RELAY_MEMBERS], limit: 1 }
6755
+
6756
+ /**
6757
+ * The workspace's owners and admins: the `member` tags whose role is `owner`
6758
+ * or `admin` on the newest `kind:13534` signed by `relay` (the key that signed
6759
+ * the team's `kind:39000`). A roster anybody else signed means nothing.
6760
+ */
6761
+ function workspaceAdminsOf(events: readonly SignedEvent[], relay: string): string[] {
6762
+ const roster = events
6763
+ .filter((event) => event.kind === KIND_RELAY_MEMBERS && event.pubkey === relay)
6764
+ .sort((a, b) => b.created_at - a.created_at || a.id.localeCompare(b.id))[0]
6765
+ if (!roster) return []
6766
+ return roster.tags
6767
+ .filter((tag) => tag[0] === 'member' && tag[1] && FOLDER_ADMIN_ROLES.has(tag[2] ?? ''))
6768
+ .map((tag) => tag[1])
6769
+ }
6770
+
6771
+ /**
6772
+ * Who may rename and archive a team: the owners and admins its relay-signed
6773
+ * `kind:39001` lists, and, when that list names no `owner`, the workspace's
6774
+ * owners and admins on the relay-signed roster as well. A team with no 39001 at
6775
+ * all is not taken as one with no owner: nothing says who is on it. Only a
6776
+ * team (`isTeam`: it holds a `kind:30890`) is looked after this way; a DM or
6777
+ * another conversation space, whose list names no owner either, never is.
6778
+ *
6779
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-team-with-no-owner-is-looked-after-by-the-workspaces-admins.md
6780
+ */
6781
+ function teamStewardsOf(
6782
+ admins: SignedEvent | undefined,
6783
+ channel: SignedEvent | undefined,
6784
+ events: readonly SignedEvent[],
6785
+ isTeam: boolean,
6786
+ ): string[] {
6787
+ const own = folderAdminsOf(admins, channel)
6788
+ if (!isTeam || !admins || !channel || admins.pubkey !== channel.pubkey) return own
6789
+ if (channel.tags.some((tag) => tag[0] === 't' && tag[1] === 'dm')) return own
6790
+ const hasOwner = admins.tags.some((tag) => tag[0] === 'p' && tag[1] && tag.slice(2).includes('owner'))
6791
+ return hasOwner ? own : [...new Set([...own, ...workspaceAdminsOf(events, channel.pubkey)])]
6792
+ }
6793
+
6681
6794
  /**
6682
6795
  * A Folder's own archive (SPEC §3.2): the `archived` changes on its channel's
6683
- * address, counting only one carrying the Folder's own `h` whose author the
6684
- * relay lists as its owner or admin. From anybody else the relay accepts the
6796
+ * address, counting only one carrying the Folder's own `h` whose author is in
6797
+ * its {@link FolderSummary.admins} (its owners and admins, and on a team with
6798
+ * no owner the workspace's too). From anybody else the relay accepts the
6685
6799
  * change, and it means nothing.
6686
6800
  */
6687
6801
  function folderArchiveOf(changes: SignedEvent[], folder: Pick<FolderSummary, 'id' | 'channel' | 'admins'>): Archive | undefined {
@@ -6724,8 +6838,12 @@ export interface FolderSummary {
6724
6838
  company?: true
6725
6839
  /**
6726
6840
  * Who may rename and archive it: the owners and admins on its relay-signed
6727
- * `kind:39001`. Offer Archive only to them — a reader ignores an archive from
6728
- * anybody else (§3.2). Absent when the relay returned no admin list.
6841
+ * `kind:39001` and, on a team whose 39001 lists no owner, the workspace's
6842
+ * owners and admins on the relay-signed roster (`kind:13534`) too. Offer
6843
+ * Archive only to them — a reader ignores an archive from anybody else
6844
+ * (§3.2). Absent when the relay returned no admin list.
6845
+ *
6846
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-team-with-no-owner-is-looked-after-by-the-workspaces-admins.md
6729
6847
  */
6730
6848
  admins?: string[]
6731
6849
  /**
@@ -6837,7 +6955,8 @@ export interface FolderContents extends FolderSummary {
6837
6955
  *
6838
6956
  * Both shapes in one pass: folders the relay maintains state for, and bare
6839
6957
  * channels that have none yet. A channel with state appears once, titled by its
6840
- * `kind:39000` (SPEC §3.2), with the owners and admins its `kind:39001` lists.
6958
+ * `kind:39000` (SPEC §3.2), with who may rename and archive it
6959
+ * ({@link FolderSummary.admins}).
6841
6960
  *
6842
6961
  * **A direct route, deliberately.** §4.2's post-mortem on REW-11 is that
6843
6962
  * discovering children only through their parent loses them when the parent
@@ -6946,6 +7065,8 @@ async function readFolderRecords(query: QueryFn): Promise<{ events: SignedEvent[
6946
7065
  { kinds: [KIND_FOLDER_STATE], limit: 500 },
6947
7066
  { kinds: [KIND_CHANNEL], limit: 500 },
6948
7067
  { kinds: [KIND_CHANNEL_ADMINS], limit: 500 },
7068
+ // Who looks after a team with no owner (FolderSummary.admins). Same request.
7069
+ RELAY_MEMBERS_FILTER,
6949
7070
  ])
6950
7071
  const byId = new Map<string, FolderSummary>()
6951
7072
  const channelOf = new Map<string, SignedEvent>()
@@ -6976,7 +7097,7 @@ async function readFolderRecords(query: QueryFn): Promise<{ events: SignedEvent[
6976
7097
  if (name !== undefined) folder.name = name
6977
7098
  if (channel.tags.some((tag) => tag[0] === 'private')) folder.private = true
6978
7099
  if (channel.tags.some((tag) => tag[0] === 'company')) folder.company = true
6979
- const admins = folderAdminsOf(adminsOf.get(id), channel)
7100
+ const admins = teamStewardsOf(adminsOf.get(id), channel, events, folder.hasState)
6980
7101
  if (admins.length) folder.admins = admins
6981
7102
  folder.channel = pointerToAddress({ kind: KIND_CHANNEL, pubkey: channel.pubkey, identifier: id, relays: [] })
6982
7103
  }
@@ -7412,12 +7533,17 @@ export async function resolveFolderContents(
7412
7533
  { kinds: [KIND_FOLDER_STATE], '#d': [folder], limit: 1 },
7413
7534
  { kinds: [KIND_CHANNEL], '#d': [folder], limit: 1 },
7414
7535
  { kinds: [KIND_CHANNEL_ADMINS], '#d': [folder], limit: 1 },
7536
+ // Who looks after it, and every team it lists, when one has no owner. Same request.
7537
+ RELAY_MEMBERS_FILTER,
7415
7538
  ])
7416
7539
  const state = identity.find((e) => e.kind === KIND_FOLDER_STATE && tagValue(e, 'd') === folder)
7417
7540
  const channel = identity.find((e) => e.kind === KIND_CHANNEL && tagValue(e, 'd') === folder)
7418
- const admins = folderAdminsOf(
7541
+ const roster = identity.filter((e) => e.kind === KIND_RELAY_MEMBERS)
7542
+ const admins = teamStewardsOf(
7419
7543
  identity.find((e) => e.kind === KIND_CHANNEL_ADMINS && tagValue(e, 'd') === folder),
7420
7544
  channel,
7545
+ roster,
7546
+ state !== undefined,
7421
7547
  )
7422
7548
  const channelAddress = channel
7423
7549
  ? pointerToAddress({ kind: KIND_CHANNEL, pubkey: channel.pubkey, identifier: folder, relays: [] })
@@ -7531,7 +7657,7 @@ export async function resolveFolderContents(
7531
7657
  // Every change, in groups small enough that a busy Folder's changes cannot
7532
7658
  // push one file's off the page — one Folder has already had 688. Same request.
7533
7659
  ...archiveFilters(channelAddress ? [...changesAsked, channelAddress] : changesAsked),
7534
- // A Folder listed here counts its archive only from its own admins (§3.2). Same request.
7660
+ // A Folder listed here counts its archive only from who looks after it (§3.2). Same request.
7535
7661
  ...(nestedFolderIds.length ? [{ kinds: [KIND_CHANNEL_ADMINS], '#d': nestedFolderIds, limit: nestedFolderIds.length }] : []),
7536
7662
  ], query),
7537
7663
  queryChunked(rootFilters.filter((filter) => 'fields' in filter), query),
@@ -7574,9 +7700,12 @@ export async function resolveFolderContents(
7574
7700
  const nestedAdmins =
7575
7701
  pointer.kind === KIND_CHANNEL
7576
7702
  ? new Set(
7577
- folderAdminsOf(
7703
+ teamStewardsOf(
7578
7704
  events.find((e) => e.kind === KIND_CHANNEL_ADMINS && tagValue(e, 'd') === pointer.identifier),
7579
7705
  root,
7706
+ roster,
7707
+ // A team listed in this one; a DM listed here is still never looked after.
7708
+ true,
7580
7709
  ),
7581
7710
  )
7582
7711
  : undefined