@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/CHANGELOG.md +33 -0
- package/README.md +3 -2
- package/dist/folders.d.ts +5 -4
- package/dist/folders.d.ts.map +1 -1
- package/dist/folders.js +5 -4
- package/dist/folders.js.map +1 -1
- package/dist/projection.d.ts +20 -3
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +120 -10
- package/dist/projection.js.map +1 -1
- package/package.json +1 -1
- package/src/folders.ts +5 -4
- package/src/projection.ts +142 -13
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@estiva-app/interop",
|
|
3
|
-
"version": "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`
|
|
225
|
-
*
|
|
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
|
|
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
|
|
3946
|
-
const
|
|
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
|
|
6684
|
-
*
|
|
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
|
|
6728
|
-
*
|
|
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
|
|
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 =
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|