@estiva-app/interop 0.83.0 → 0.84.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.83.0",
3
+ "version": "0.84.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/index.ts CHANGED
@@ -29,6 +29,7 @@ export {
29
29
  resolveActingManifest,
30
30
  resolveForeignObject,
31
31
  resolveForeignObjects,
32
+ prevOf,
32
33
  resolveForeignRoots,
33
34
  projectListedFiles,
34
35
  projectEvents,
package/src/projection.ts CHANGED
@@ -186,6 +186,7 @@ function pubkeysIn(object: ForeignObject): string[] {
186
186
  for (const action of object.actions) {
187
187
  if (action.control === 'pubkey' && action.current) keys.push(action.current)
188
188
  }
189
+ if (object.deleted) keys.push(object.deleted.by)
189
190
  return keys
190
191
  }
191
192
 
@@ -2391,7 +2392,7 @@ function inTargetFolder(change: SignedEvent, folders: ReadonlySet<string> | unde
2391
2392
  * version where several are.
2392
2393
  */
2393
2394
  function foldChanges(changes: SignedEvent[], rule: RecordsRule, root: SignedEvent | undefined) {
2394
- const fields: Record<string, { value: string; by: string; at: number; format: ContentFormat }> = {}
2395
+ const fields: Record<string, { value: string; by: string; at: number; format: ContentFormat; id: string }> = {}
2395
2396
  const folders = targetFolders(root)
2396
2397
  const id = root && tagValue(root, 'd')
2397
2398
  for (const change of [...changes].filter((c) => inTargetFolder(c, folders)).sort(byOrder)) {
@@ -2402,6 +2403,9 @@ function foldChanges(changes: SignedEvent[], rule: RecordsRule, root: SignedEven
2402
2403
  // A summary is new, so it takes neither of §6.2's exceptions: a change the
2403
2404
  // reader cannot check against the root's Folder is not read (SPEC §6.12).
2404
2405
  if (field === SUMMARY_FIELD && !folders) continue
2406
+ // A delete is by "anyone who may write in the file's team" (SPEC §6.5), and
2407
+ // a root that names no team has none: no change can delete it.
2408
+ if (field === DELETED_FIELD && !folders) continue
2405
2409
  // The format travels with the *winning* change, not with the object. SPEC
2406
2410
  // §13.4: "an app MUST read the tag from the event it took the value from,
2407
2411
  // never from the object's root" — a description created as marker text and
@@ -2411,6 +2415,7 @@ function foldChanges(changes: SignedEvent[], rule: RecordsRule, root: SignedEven
2411
2415
  by: change.pubkey,
2412
2416
  at: change.created_at,
2413
2417
  format: contentFormatOf(change),
2418
+ id: change.id,
2414
2419
  }
2415
2420
  }
2416
2421
  }
@@ -3352,6 +3357,33 @@ export interface ForeignObject {
3352
3357
  * `created_at`. Absent on an unreachable stub, which has no root to read.
3353
3358
  */
3354
3359
  changedAt?: number
3360
+ /**
3361
+ * Each changed field's current change id: the `prev` a change to that field
3362
+ * names (SPEC §6.2). A field never changed is absent, and its first change
3363
+ * names the first record — {@link prevOf} answers both. Absent on a regular
3364
+ * event and an unreachable stub. A file read by a list carries no text: its
3365
+ * text's entry is `''`, and {@link prevOf} answers undefined for it.
3366
+ *
3367
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-file-is-its-fields-each-kept-in-order-by-the-relay.md
3368
+ */
3369
+ prevs?: Record<string, string>
3370
+ /**
3371
+ * Set when the file's newest `deleted` change is `true` (SPEC §6.5): who
3372
+ * deleted it and when, in seconds. A deleted file is still read by its id, for
3373
+ * the notice that says so and its Restore.
3374
+ */
3375
+ deleted?: { by: string; at: number }
3376
+ }
3377
+
3378
+ /**
3379
+ * The change a change to `field` of `object` follows (SPEC §6.2): its current
3380
+ * change, else the first record. Undefined for the text of a file read by a
3381
+ * list, which carries no text: open it to write it.
3382
+ */
3383
+ export function prevOf(object: Pick<ForeignObject, 'prevs' | 'eventId'>, field: string): string | undefined {
3384
+ const id = object.prevs?.[field]
3385
+ if (id === '') return undefined
3386
+ return id ?? object.eventId
3355
3387
  }
3356
3388
 
3357
3389
  /** The newest of a root's `created_at` and its folded fields' changes. */
@@ -3371,7 +3403,7 @@ function buildObject(args: {
3371
3403
  pointer: AddressPointer
3372
3404
  manifest: Manifest
3373
3405
  projection: Projection
3374
- folded: Record<string, { value: string; format?: ContentFormat; at?: number }>
3406
+ folded: Record<string, { value: string; format?: ContentFormat; at?: number; by?: string; id?: string }>
3375
3407
  viaRecommendation: boolean
3376
3408
  webTemplate?: string
3377
3409
  comments?: ForeignObject['comments']
@@ -3381,6 +3413,9 @@ function buildObject(args: {
3381
3413
  const naddr = encodeNaddr(pointer)
3382
3414
  const { slots, meta } = resolveSlots(projection, root, folded, manifest)
3383
3415
  const objectAddress = pointerToAddress(pointer)
3416
+ // A list read's text placeholder keeps its empty id: the text's `prev` is unknown there, not the first record.
3417
+ const prevs = Object.fromEntries(Object.entries(folded).flatMap(([field, f]) => (f.id !== undefined ? [[field, f.id]] : [])))
3418
+ const deleted = folded[DELETED_FIELD]
3384
3419
  return {
3385
3420
  // An addressable object's `ref` is its address: stable across the author
3386
3421
  // replacing the event, which the event id is not.
@@ -3407,9 +3442,14 @@ function buildObject(args: {
3407
3442
  viaRecommendation: args.viaRecommendation,
3408
3443
  ...(args.archived ? { archived: args.archived } : {}),
3409
3444
  changedAt: changedAtOf(root, folded),
3445
+ ...(Object.keys(prevs).length ? { prevs } : {}),
3446
+ ...(deleted?.value === 'true' && deleted.by ? { deleted: { by: deleted.by, at: deleted.at ?? root.created_at } } : {}),
3410
3447
  }
3411
3448
  }
3412
3449
 
3450
+ /** The field a file is deleted by (SPEC §6.5): `true` deletes it, the empty value restores it. */
3451
+ const DELETED_FIELD = 'deleted'
3452
+
3413
3453
  /**
3414
3454
  * An addressable file's actions, each with what its field holds now, however
3415
3455
  * it got there.
@@ -3553,19 +3593,21 @@ export async function resolveForeignObject(
3553
3593
  if (!pointer) return null
3554
3594
  const resolved = await resolveManifest(pointer, query, cache)
3555
3595
  if (!resolved) return null
3556
- const plan = planObject(naddr, pointer, resolved, depth)
3596
+ const plan = planObject(naddr, pointer, resolved, depth, options.openRead)
3557
3597
  if (!plan) return null
3558
3598
 
3559
3599
  // Beside the object's own read, not after it: the sweep is cached, and cold
3560
3600
  // it would otherwise add a round trip to every resolve that pays for it.
3561
3601
  // A Folder card's files too, for the same reason.
3562
- const [answered, creators, files] = await Promise.all([
3602
+ const [read, opened, creators, files] = await Promise.all([
3563
3603
  query(plan.filters),
3604
+ openedEvents([plan], query),
3564
3605
  creatorsOrNone(pointer.kind, query, cache),
3565
3606
  options.folderFiles && pointer.kind === KIND_CHANNEL_METADATA
3566
3607
  ? folderFilesOf(pointer.identifier, query, lookupPeople, cache)
3567
3608
  : undefined,
3568
3609
  ])
3610
+ const answered = [...read, ...opened]
3569
3611
  const followUp = childChangeFilters(plan, answered)
3570
3612
  const childChanges = followUp.length ? await queryChunked(followUp, query) : []
3571
3613
  const childOwners = await childOwnersOf(plan, answered, childChanges, query, cache)
@@ -3662,7 +3704,7 @@ export async function resolveForeignObjects(
3662
3704
 
3663
3705
  const plans = asked.flatMap(({ reference, pointer }) => {
3664
3706
  const resolved = manifests.get(manifestKeyOf(pointer))
3665
- const plan = resolved && planObject(reference, pointer, resolved, 0)
3707
+ const plan = resolved && planObject(reference, pointer, resolved, 0, options.openRead)
3666
3708
  return plan ? [{ reference, plan }] : []
3667
3709
  })
3668
3710
  if (plans.length === 0) return results
@@ -3687,11 +3729,13 @@ export async function resolveForeignObjects(
3687
3729
  ),
3688
3730
  ]
3689
3731
  : []
3690
- const [events, creatorLists, fileLists] = await Promise.all([
3732
+ const [read, opened, creatorLists, fileLists] = await Promise.all([
3691
3733
  queryChunked(filters, query),
3734
+ openedEvents(plans.map(({ plan }) => plan), query),
3692
3735
  Promise.all(kinds.map((kind) => creatorsOrNone(kind, query, cache))),
3693
3736
  Promise.all(folders.map((folder) => folderFilesOf(folder, query, lookupPeople, cache))),
3694
3737
  ])
3738
+ const events = [...read, ...opened]
3695
3739
  const creatorsByKind = new Map(kinds.map((kind, i) => [kind, creatorLists[i]]))
3696
3740
  const filesByFolder = new Map(folders.map((folder, i) => [folder, fileLists[i]]))
3697
3741
 
@@ -3900,7 +3944,8 @@ export async function resolveForeignRoots(
3900
3944
  if (filters.length === 0 && listed.length === 0) return []
3901
3945
  // A relay refuses a request mixing list reads with plain ones, so each goes on its own.
3902
3946
  const events = (await Promise.all([queryChunked(filters, query), queryChunked(listed, query)])).flat()
3903
- const objects = projectEvents(events, (pointer) => manifests.get(manifestKeyOf(pointer)))
3947
+ const projected = projectEvents(events, (pointer) => manifests.get(manifestKeyOf(pointer)))
3948
+ const objects = options.listRead ? textUnread(projected) : projected
3904
3949
  if (options.archivedWith) {
3905
3950
  const manifestOf = (object: ForeignObject) => {
3906
3951
  const pointer = object.address ? addressPointerOf(object.address) : undefined
@@ -3939,7 +3984,18 @@ export async function projectListedFiles(events: readonly SignedEvent[], query:
3939
3984
  }
3940
3985
  if (pointers.length === 0) return []
3941
3986
  const manifests = await manifestsOf(pointers, query, cache)
3942
- return projectEvents(events, (pointer) => manifests.get(manifestKeyOf(pointer)))
3987
+ return textUnread(projectEvents(events, (pointer) => manifests.get(manifestKeyOf(pointer))))
3988
+ }
3989
+
3990
+ /**
3991
+ * Files read by a list carry no text (§6.13), and a change that set it with other
3992
+ * fields may be stale: the text's `prev` is unknown, `''`, so {@link prevOf}
3993
+ * answers nothing for it rather than an old change or the first record.
3994
+ */
3995
+ function textUnread(objects: ForeignObject[]): ForeignObject[] {
3996
+ return objects.map((object) =>
3997
+ FILE_KINDS.includes(object.kind) ? { ...object, prevs: { ...object.prevs, description: '' } } : object,
3998
+ )
3943
3999
  }
3944
4000
 
3945
4001
  /**
@@ -4082,6 +4138,19 @@ export interface ArchiveReadOptions {
4082
4138
  * changes are read either way.
4083
4139
  */
4084
4140
  archivedChildren?: boolean
4141
+ /**
4142
+ * The file kinds to open by the relay's open read (SPEC §6.13, "Opening a
4143
+ * file reads its current text too"): the first record, each field's current
4144
+ * change and the current text, however long its history — not every change by
4145
+ * `#a`. Pass it only where NIP-11's `file_list` says `text` (`relayFileReadsOf`
4146
+ * in `@estiva-app/protocol`), and only the kinds the app has switched; the rest
4147
+ * are read as before. A file the open read does not answer (deleted, or not
4148
+ * this reader's) is read as before too, so a deleted one still says who
4149
+ * deleted it.
4150
+ *
4151
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/opening-a-file-reads-its-current-text-not-its-history.md
4152
+ */
4153
+ openRead?: readonly number[]
4085
4154
  }
4086
4155
 
4087
4156
  /**
@@ -4342,6 +4411,10 @@ interface ObjectPlan {
4342
4411
  commentKinds: number[]
4343
4412
  childFilter: ReturnType<typeof childFilterFor>
4344
4413
  filters: Record<string, unknown>[]
4414
+ /** Read by the open read ({@link ArchiveReadOptions.openRead}), so `filters` holds neither its root nor its changes. */
4415
+ opened: boolean
4416
+ /** Its root and every change, as read before the open read: for a file that read does not answer. */
4417
+ history: Record<string, unknown>[]
4345
4418
  openUrl?: string
4346
4419
  }
4347
4420
 
@@ -4351,6 +4424,7 @@ function planObject(
4351
4424
  pointer: AddressPointer,
4352
4425
  resolved: ResolvedManifest,
4353
4426
  depth: number,
4427
+ openRead?: readonly number[],
4354
4428
  ): ObjectPlan | null {
4355
4429
  const { manifest } = resolved
4356
4430
  const address = pointerToAddress(pointer)
@@ -4380,18 +4454,55 @@ function planObject(
4380
4454
  one, and with the manifest memoised it is the whole cost of a tick.
4381
4455
  */
4382
4456
  const childFilter = childFilterFor({ projection, manifest, pointer, depth })
4383
- const filters = [
4457
+ const history = [
4384
4458
  { kinds: [pointer.kind], authors: [pointer.pubkey], '#d': [pointer.identifier], limit: 1 },
4385
4459
  // Only when the app actually declares a change kind — see `foldRuleOf`.
4386
4460
  ...(manifest.records ? [{ kinds: [manifest.records.changeKind], '#a': [address], limit: 500 }] : []),
4387
4461
  // Every file may be archived, including one whose app folds nothing
4388
4462
  // (FOL-46). SPEC's change kind, when the app has not named its own.
4389
4463
  ...(manifest.records ? [] : [{ kinds: [ARCHIVE_RULE.changeKind], '#a': [address], limit: 500 }]),
4464
+ ]
4465
+ const opened = !!openRead?.includes(pointer.kind) && FILE_KINDS.includes(pointer.kind)
4466
+ const filters = [
4467
+ ...(opened ? [] : history),
4390
4468
  { kinds: commentKinds, '#a': [address], limit: CONVERSATION_LIMIT },
4391
4469
  ...(childFilter ? [childFilter.filter] : []),
4392
4470
  ...(childFilter?.movedIn ? [childFilter.movedIn] : []),
4393
4471
  ]
4394
- return { naddr, pointer, address, resolved, projection, records, commentKinds, childFilter, filters, openUrl }
4472
+ return { naddr, pointer, address, resolved, projection, records, commentKinds, childFilter, filters, opened, history, openUrl }
4473
+ }
4474
+
4475
+ /**
4476
+ * What the open read answers for the planned files it opens (SPEC §6.13): one
4477
+ * read per author and kind, apart from the plain reads, since a relay refuses a
4478
+ * request mixing the two. A file it does not answer — deleted, or not this
4479
+ * reader's — has its root and every change read as before, so a deleted file
4480
+ * still says who deleted it and an unreadable one is still told apart from it.
4481
+ */
4482
+ async function openedEvents(plans: readonly ObjectPlan[], query: QueryFn): Promise<SignedEvent[]> {
4483
+ const opened = new Map<string, ObjectPlan>()
4484
+ for (const plan of plans) if (plan.opened) opened.set(plan.address, plan)
4485
+ if (opened.size === 0) return []
4486
+ const groups = new Map<string, { kind: number; pubkey: string; identifiers: string[] }>()
4487
+ for (const { pointer } of opened.values()) {
4488
+ const key = `${pointer.kind}:${pointer.pubkey}`
4489
+ const group = groups.get(key) ?? { kind: pointer.kind, pubkey: pointer.pubkey, identifiers: [] }
4490
+ group.identifiers.push(pointer.identifier)
4491
+ groups.set(key, group)
4492
+ }
4493
+ const filters: Record<string, unknown>[] = []
4494
+ for (const { kind, pubkey, identifiers } of groups.values()) {
4495
+ for (let start = 0; start < identifiers.length; start += RELAY_PAGE_CEILING) {
4496
+ const chunk = identifiers.slice(start, start + RELAY_PAGE_CEILING)
4497
+ filters.push({ fields: 'newest', kinds: [kind], authors: [pubkey], '#d': chunk, limit: chunk.length, text: true })
4498
+ }
4499
+ }
4500
+ const answered = await queryChunked(filters, query)
4501
+ const unanswered = [...opened.values()].filter(
4502
+ ({ pointer }) => !answered.some((e) => e.kind === pointer.kind && e.pubkey === pointer.pubkey && tagValue(e, 'd') === pointer.identifier),
4503
+ )
4504
+ const history = unanswered.length ? await queryChunked(unanswered.flatMap((plan) => plan.history), query) : []
4505
+ return [...answered, ...history]
4395
4506
  }
4396
4507
 
4397
4508
  /** An object and its children, before the people lookup that needs both. */
@@ -7251,7 +7362,7 @@ export async function resolveFolderContents(
7251
7362
  // other fields may be stale: the text is unread, never the seed the file
7252
7363
  // was created with drawn as if it were current.
7253
7364
  if (byFields(pointer.kind)) {
7254
- folded.description = { value: '', by: root.pubkey, at: root.created_at, format: 'marker' }
7365
+ folded.description = { value: '', by: root.pubkey, at: root.created_at, format: 'marker', id: '' }
7255
7366
  }
7256
7367
  const nestedAdmins =
7257
7368
  pointer.kind === KIND_CHANNEL