@usehandout/cli 1.3.0 → 1.5.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.
Files changed (3) hide show
  1. package/SKILL.md +22 -6
  2. package/handout.mjs +402 -104
  3. package/package.json +1 -1
package/SKILL.md CHANGED
@@ -86,7 +86,8 @@ Every command takes the global flags `--workspace/-w`, `--host`, `--json`, `--qu
86
86
  | `versions` | `handout versions list q3-report` | list, `source`, `restore`, `prune --keep <n>`, `diff <slug> <v1> <v2>` |
87
87
  | `invite` | `handout invite q3-report --to a@b.com` | a confirmation line |
88
88
  | `activity` / `audit` / `acks` | `handout activity q3-report` | views, history, acknowledgments |
89
- | `list` | `handout list --label finance` | url, audience, type, title per line |
89
+ | `list` | `handout list --label report` | url, audience, type, title per line; `--collection <slug>` filters to one collection |
90
+ | `labels` | `handout labels --json` | the workspace's suggested labels with usage counts |
90
91
  | `get` | `handout get q3-report` | a key/value block |
91
92
  | `search` | `handout search "quarterly"` | slug, where it matched, title |
92
93
  | `source` | `handout source q3-report --out report.md` | the source file |
@@ -110,6 +111,20 @@ Every command takes the global flags `--workspace/-w`, `--host`, `--json`, `--qu
110
111
 
111
112
  `handout --version` prints the installed version. `handout <command> --help` prints that command's flags.
112
113
 
114
+ ## Labels and collections
115
+
116
+ **The rule: a label says what kind of document it is; a collection says what it belongs to.** `plan`, `spec`, `report`, `review`, `guide`, `notes`, `proposal` and `prototype` are labels. A project, a client, a quarter or a team (`handout`, `q3`, `contoso`) is a collection. Never use a status (`draft`, `final`) as a label.
117
+
118
+ Each workspace keeps a short, editable list of suggested labels. Before you label anything:
119
+
120
+ 1. Run `handout labels --json`. `suggested` is the list, each entry with the number of documents that carry it; `other` is labels in use that are not suggested.
121
+ 2. Pick from `suggested`, one or two per document. Reuse an existing spelling instead of a variant (`Plan` vs `plan`).
122
+ 3. If nothing on the list fits, **ask the user before inventing a label**. A free-text label is still accepted, but a guessed one becomes a permanent near-duplicate. When `suggested` is empty and `seedable` is true, the workspace already uses labels and has no list yet: do not invent one; tell the user they can adopt the suggested set on the workspace's settings page.
123
+ 4. When two or more documents share a project, client or period, **suggest a collection** (`handout collections create` and `collections add`) instead of a label, and ask before creating it. `handout list --collection <slug>` lists what is in one, and `handout get <slug>` shows the collections a document is in. Never label a document with its collection's name.
124
+ 5. A `suggested` or `other` entry may carry `matchesCollection: { slug, name }`: every document with that label is exactly the members of that collection, so the label stores the same fact twice. **Suggest the collection to the user** ("Every document labelled `q3` is already in the Q3 pack collection; use the collection instead?") and do not apply that label to new documents. It is a suggestion only: never remove the label, add or remove collection members, or delete anything because of it unless the user says to.
125
+
126
+ The user's account `defaultLabels` setting is separate: it stamps labels on every publish, and you never change it unless asked.
127
+
113
128
  ## Publish what you just generated
114
129
 
115
130
  1. Write the file to disk first; the CLI publishes files, not stdin. Use the extension that matches the content (`.html`, `.md`, `.pdf`) or pass `--content-type`. Word (`.docx`) is not supported: export it as PDF, or convert it to Markdown or HTML first. A document may be up to 20 MB (the account's limit can be lower; the CLI reports it).
@@ -117,8 +132,9 @@ Every command takes the global flags `--workspace/-w`, `--host`, `--json`, `--qu
117
132
  3. For rich HTML, run the grep checklist in the HTML authoring section and fix every hit, or publish `--interactive` when the document genuinely needs scripts and the user accepts the audience rule.
118
133
  4. Read the account publishing defaults as described above. Explicit audience requests override them: "just for me" is `--exposure private`; "the team" is `--exposure people --people @acme.com`; named people or a domain is `--people a@b.com --people @acme.com` (this implies `people`); "anyone with the link" is `--exposure open`; "with a password" is `--password -` (reads the password from stdin, so it stays out of the process list). Otherwise omit `--exposure` to honor the saved account default, falling back to `private` server-side. Never explicitly select `open` without a user instruction; an existing saved default is applied by the server, not rewritten as a hardcoded flag.
119
134
  5. Give it a short, real title: the document's own `<title>` or first heading, or `--title "<short title>"` when it has none (always for a PDF). The link is made from the title plus 8 random characters (`q3-report-k7f2qx9a`), so it reads well and still can't be guessed. Anyone who sees the link sees those title words, whatever the audience, so for a sensitive document ask the user for a neutral title. Leave out `--slug` unless the user asks for a specific link; then pass a short kebab-case one (`--slug q3-report`) and tell them a link like that can be guessed by anyone who knows the workspace, which matters for "anyone with the link" and password documents.
120
- 6. Run `handout publish <file> [--exposure ...] [--title ...] [--label ...] --json` and read `items[0].url`, `slug`, `version` and `warnings`.
135
+ 6. Choose labels as described in Labels and collections (`handout labels --json`, pick from `suggested`, ask before inventing one). Run `handout publish <file> [--exposure ...] [--title ...] [--label ...] --json` and read `items[0].url`, `slug`, `version` and `warnings`.
121
136
  7. Report the URL to the user verbatim. If `warnings` is not empty, summarise each in one line and offer to fix the file and run `handout update <slug> <file>`.
137
+ A `pdf_no_text` warning means the PDF is published but "We couldn't find much searchable text in this PDF. If it's a scan, running OCR and republishing will make it searchable." Pass that on in one line, then offer to make it searchable: run text recognition (OCR) on the file locally and publish the result as a new version of the same document. Ask the user first; never OCR or republish unasked. When they agree and `ocrmypdf` is installed (`ocrmypdf --version`), run `ocrmypdf --skip-text <file> <file-ocr>.pdf`, then `handout update <slug> <file-ocr>.pdf --diff-summary "Made the text searchable."`. If no OCR tool is available, tell them and leave the document as it is. Handout itself never runs OCR.
122
138
  8. If the slug came back as 12 random characters (`aB3xY9zQ1pR7`), the document had no usable title. Rename it at once, before the link is shared, since a rename breaks the old link: `handout rename <slug> <kebab-case-title>-<8 random lowercase letters and digits>`. Give later versions a title.
123
139
  9. Remember the slug for the rest of the conversation. Later edits are `handout update <slug> <file>` (same link, new version), never a second `publish`, which mints a second link. `handout upsert <file> --slug <slug>` creates or updates in one call when you already know the slug.
124
140
  Every update carries a change note by default: `--diff-summary "<one line on what changed>"`, written for the readers ("Added the Q4 numbers and fixed the totals table."), not as a commit message. Readers who come back see it as "What's new in v{n}", followers get it in their update email, and it is listed in the version history. Keep it to one sentence (it shows up to 280 characters; 500 is the hard limit), never paste the document or anything secret into it, and leave it out only when the user asks.
@@ -130,9 +146,9 @@ For retry safety without `upsert`, generate one UUID per logical publish and pas
130
146
 
131
147
  Before writing a document from scratch, before answering "where is the ...", and before any command that takes a slug the user did not give verbatim:
132
148
 
133
- 1. Run `handout search "<two or more words from the request>" --json`. Use `handout list --json` (optionally `--label`) for browse-shaped requests, and `handout library --json` or `handout shared --json` when the user is a reader rather than the publisher.
149
+ 1. Run `handout search "<two or more words from the request>" --json`. Use `handout list --json` (optionally `--label` for a kind of document or `--collection` for a project) for browse-shaped requests, and `handout library --json` or `handout shared --json` when the user is a reader rather than the publisher.
134
150
  2. Exactly one match: confirm the slug and title with the user in one line, then proceed. Several: present `slug - title (updated)` candidates and ask; never pick the first row silently. None: say so and offer to publish anew (or `collections create` for a collection).
135
- 3. Resolve labels the same way: collect the union of `labels` from `handout list --json` and reuse an existing spelling when the requested label is only a case or hyphenation variant (`Q3` vs `q3` vs `q3-report`). Apply a genuinely new label as given.
151
+ 3. Resolve labels from `handout labels --json`, not by guessing: reuse the suggested spelling when the requested label is only a case or hyphenation variant (`Report` vs `report`), and when the request names a topic or project (`finance`, `Q3`) treat it as a collection, not a label. If no suggested label fits, ask the user before creating one.
136
152
  4. Resolve a collection by `handout collections list --json` and fuzzy-matching the user's words against `name`; confirm before `collections add` or `--collection`.
137
153
  5. If the user pasted a Handout link, pass it as the `<ref>` directly; the CLI accepts links and `<handle>/<slug>`.
138
154
  6. Ambiguity is always the user's call. A guessed slug is a `404`, and a guessed label is a permanent near-duplicate.
@@ -149,7 +165,7 @@ Before writing a document from scratch, before answering "where is the ...", and
149
165
  - `--people` takes email addresses and whole domains (`@contoso.example`), repeatable or comma-separated, at most 200 entries; it implies `--exposure people`. `--invite <email>` (at most 25) also emails the people a link.
150
166
  - `--password <secret>` is 4 to 128 characters and implies `--exposure password`. Prefer `--password -` or the `HANDOUT_DOCUMENT_PASSWORD` variable over a literal argument.
151
167
  - Link controls: `--expires <when>` (a date, or a duration such as `7d`, `24h`, `30m`), `--max-views <n>`, `--one-time`, and `--revoke` / `--restore` on `manage`.
152
- - Labels: `--label <name>`, repeatable, at most 10 per document, 1 to 24 characters each.
168
+ - Labels: `--label <name>`, repeatable, at most 10 per document, 1 to 24 characters each. A label says what kind of document it is; pick from `handout labels --json`.
153
169
  - Listing: new documents are unlisted (kept off the publisher's public page). Pass `--no-unlisted` ("show on my public page") only when the user asks for that.
154
170
  - Other switches: `--unlisted`, `--notify-on-view`, `--request-ack` (not with `--exposure password` or `open`: only signed-in readers of a private or people document can acknowledge), `--allow-source-download`, `--allow-external-images`, and for PDFs `--view-only` and `--watermark`.
155
171
 
@@ -263,7 +279,7 @@ An interactive page may only talk to the origins you allow with `--connect-src <
263
279
  Each line shows the command and its expected output.
264
280
 
265
281
  1. `handout publish report.html` prints `https://handout.app/acme/q3-report-k7f2qx9a` (the link comes from the document's title, `Q3 report`).
266
- 2. `handout publish report.md --exposure open --title "Q3 report" --label finance --label q3 --json` prints `{"items":[{"file":"report.md","handle":"acme","slug":"...","id":"...","url":"...","exposure":"open","version":1,...}]}`.
282
+ 2. `handout publish report.md --exposure open --title "Q3 report" --label report --json` prints `{"items":[{"file":"report.md","handle":"acme","slug":"...","id":"...","url":"...","exposure":"open","version":1,...}]}`.
267
283
  3. `handout publish deck.pdf --people vicki@contoso.example --people @contoso.example --invite vicki@contoso.example` prints the URL (stderr: `published acme/... v1 pdf 2.3 MB people`).
268
284
  4. `handout publish spec.html --exposure password --password - < pw.txt` prints the URL.
269
285
  5. `handout update q3-report report.md --diff-summary "Added the Q4 numbers."` prints the same URL (stderr: `updated acme/q3-report v2 ...`); returning readers see "What's new in v2: Added the Q4 numbers."
package/handout.mjs CHANGED
@@ -19527,10 +19527,180 @@ var Ulid = external_exports.string().regex(ULID_PATTERN, { message: "Expected a
19527
19527
  var IsoInstant = external_exports.iso.datetime();
19528
19528
  var OperatorRole = external_exports.string();
19529
19529
  var CanList = external_exports.array(external_exports.string());
19530
+ var ReportReason = external_exports.enum([
19531
+ "spam",
19532
+ "phishing",
19533
+ "malware",
19534
+ "copyright",
19535
+ "illegal",
19536
+ "harassment",
19537
+ "other",
19538
+ "privacy",
19539
+ "intimate_imagery",
19540
+ "child_safety",
19541
+ "imminent_danger",
19542
+ "official_order"
19543
+ ]);
19544
+ var standard = {
19545
+ urgent: false,
19546
+ deadline: { businessDays: 1 },
19547
+ restricted: false,
19548
+ noContentView: false,
19549
+ uncapped: false,
19550
+ elevatedLift: false
19551
+ };
19552
+ var REPORT_CATEGORY_POLICY = {
19553
+ spam: standard,
19554
+ harassment: standard,
19555
+ privacy: standard,
19556
+ illegal: standard,
19557
+ other: standard,
19558
+ phishing: { ...standard, urgent: true, deadline: { hours: 24 }, acknowledgeWithinHours: 4 },
19559
+ malware: { ...standard, urgent: true, deadline: { hours: 24 }, acknowledgeWithinHours: 4 },
19560
+ copyright: { ...standard, deadline: { businessDays: 2 } },
19561
+ official_order: {
19562
+ ...standard,
19563
+ urgent: true,
19564
+ deadline: { businessDays: 5 },
19565
+ acknowledgeWithinHours: 4,
19566
+ elevatedLift: true
19567
+ },
19568
+ intimate_imagery: {
19569
+ ...standard,
19570
+ urgent: true,
19571
+ deadline: { hours: 48 },
19572
+ restricted: true,
19573
+ acknowledgeWithinHours: 4,
19574
+ elevatedLift: true
19575
+ },
19576
+ child_safety: {
19577
+ urgent: true,
19578
+ deadline: { hours: 24 },
19579
+ restricted: true,
19580
+ noContentView: true,
19581
+ uncapped: true,
19582
+ acknowledgeWithinHours: 1,
19583
+ elevatedLift: true
19584
+ },
19585
+ imminent_danger: {
19586
+ ...standard,
19587
+ urgent: true,
19588
+ deadline: { hours: 1 },
19589
+ uncapped: true,
19590
+ acknowledgeWithinHours: 1,
19591
+ elevatedLift: true
19592
+ }
19593
+ };
19594
+ var HOUR_MS = 60 * 60 * 1000;
19595
+ var DAY_MS = 24 * HOUR_MS;
19596
+ var ReportDate = external_exports.string().regex(/^\d{4}-\d{2}-\d{2}$/);
19597
+ var ReportNotice = external_exports.object({
19598
+ work: external_exports.string().trim().min(1).max(1000).optional(),
19599
+ depicted: external_exports.enum(["self", "representative"]).optional(),
19600
+ authority: external_exports.string().trim().min(1).max(200).optional(),
19601
+ reference: external_exports.string().trim().min(1).max(200).optional(),
19602
+ respondBy: ReportDate.optional(),
19603
+ goodFaith: external_exports.literal(true).optional(),
19604
+ accurate: external_exports.literal(true).optional(),
19605
+ signature: external_exports.string().trim().min(1).max(200).optional()
19606
+ });
19607
+ var ReportPublicStatus = external_exports.enum([
19608
+ "received",
19609
+ "under_review",
19610
+ "closed_actioned",
19611
+ "closed_no_action"
19612
+ ]);
19613
+ var ReportStatus = external_exports.enum(["open", "dismissed", "actioned"]);
19614
+ var ReportTargetType = external_exports.enum(["document", "collection"]);
19615
+ var REPORT_DETAILS_MAX_LENGTH = 2000;
19616
+ var EvidenceItem = external_exports.object({
19617
+ id: Ulid,
19618
+ key: external_exports.string(),
19619
+ documentId: Ulid,
19620
+ version: external_exports.number().int().min(1),
19621
+ contentType: external_exports.string(),
19622
+ at: external_exports.string(),
19623
+ by: external_exports.string()
19624
+ });
19625
+ var APPEAL_STATEMENT_MAX_LENGTH = 2000;
19626
+ var APPEAL_NOTE_MAX_LENGTH = 1000;
19627
+ var CounterNotice = external_exports.object({
19628
+ name: external_exports.string().trim().min(1).max(200),
19629
+ address: external_exports.string().trim().min(1).max(500),
19630
+ phone: external_exports.string().trim().min(3).max(50),
19631
+ email: external_exports.email().max(320),
19632
+ material: external_exports.string().trim().min(1).max(1000),
19633
+ mistake: external_exports.literal(true),
19634
+ jurisdiction: external_exports.literal(true),
19635
+ signature: external_exports.string().trim().min(1).max(200)
19636
+ });
19637
+ var AppealKind = external_exports.enum(["appeal", "counter_notice"]);
19638
+ var AppealStatus = external_exports.enum([
19639
+ "open",
19640
+ "upheld",
19641
+ "reversed",
19642
+ "waiting",
19643
+ "restored",
19644
+ "suit_filed"
19645
+ ]);
19646
+ var ReportAppeal = external_exports.object({
19647
+ kind: AppealKind,
19648
+ status: AppealStatus,
19649
+ documentId: Ulid,
19650
+ at: external_exports.string(),
19651
+ by: external_exports.string(),
19652
+ statement: external_exports.string().max(APPEAL_STATEMENT_MAX_LENGTH).optional(),
19653
+ counterNotice: CounterNotice.optional(),
19654
+ dueAt: external_exports.string().optional(),
19655
+ escalatedAt: external_exports.string().optional(),
19656
+ forwardedAt: external_exports.string().optional(),
19657
+ forwardedBy: external_exports.string().optional(),
19658
+ restoreAfter: external_exports.string().optional(),
19659
+ restoreBy: external_exports.string().optional(),
19660
+ decidedAt: external_exports.string().optional(),
19661
+ decidedBy: external_exports.string().optional(),
19662
+ note: external_exports.string().max(APPEAL_NOTE_MAX_LENGTH).optional(),
19663
+ sameOperator: external_exports.boolean().optional()
19664
+ });
19665
+ var ReportRecord = external_exports.object({
19666
+ id: Ulid,
19667
+ targetType: external_exports.enum(["document", "collection", "url"]),
19668
+ submittedUrl: external_exports.string().url().max(2048).optional(),
19669
+ documentId: Ulid.optional(),
19670
+ collectionId: Ulid.optional(),
19671
+ workspaceId: Ulid.optional(),
19672
+ handle: external_exports.string(),
19673
+ slug: external_exports.string(),
19674
+ version: external_exports.number().int().min(1).optional(),
19675
+ reason: ReportReason,
19676
+ details: external_exports.string().max(REPORT_DETAILS_MAX_LENGTH).optional(),
19677
+ reporterUid: external_exports.string().optional(),
19678
+ reporterEmail: external_exports.string().optional(),
19679
+ reporterIpHash: external_exports.string().optional(),
19680
+ createdAt: external_exports.string(),
19681
+ status: ReportStatus,
19682
+ resolvedAt: external_exports.string().optional(),
19683
+ resolutionNote: external_exports.string().optional(),
19684
+ alertedAt: external_exports.string().optional(),
19685
+ digestedAt: external_exports.string().optional(),
19686
+ dueAt: external_exports.string().optional(),
19687
+ notice: ReportNotice.optional(),
19688
+ statusTokenHash: external_exports.string().optional(),
19689
+ receiptTo: external_exports.string().optional(),
19690
+ acknowledgedAt: external_exports.string().optional(),
19691
+ acknowledgedBy: external_exports.string().optional(),
19692
+ ackEscalatedAt: external_exports.string().optional(),
19693
+ overdueEscalatedAt: external_exports.string().optional(),
19694
+ evidence: external_exports.array(EvidenceItem).optional(),
19695
+ appeal: ReportAppeal.optional()
19696
+ }).refine((report) => report.targetType === "url" ? report.submittedUrl !== void 0 && report.documentId === void 0 && report.collectionId === void 0 : report.workspaceId !== void 0 && (report.targetType === "document" ? report.documentId !== void 0 && report.collectionId === void 0 : report.collectionId !== void 0 && report.documentId === void 0), {
19697
+ message: "A report names exactly one target: documentId for a document, collectionId for a collection."
19698
+ });
19530
19699
  var ContentType = external_exports.enum(["html", "markdown", "pdf"]);
19531
19700
  function isBinaryContentType(contentType) {
19532
19701
  return contentType === "pdf";
19533
19702
  }
19703
+ var MARKDOWN_MAX_BYTES = 2097152;
19534
19704
  var CONTENT_TYPE_EXTENSIONS = {
19535
19705
  html: "html",
19536
19706
  markdown: "md",
@@ -19600,6 +19770,9 @@ var AllowlistEntry = external_exports.string().trim().max(MAX_ALLOWLIST_ENTRY_LE
19600
19770
  var DocumentLabel = external_exports.string().trim().min(1).max(24);
19601
19771
  var MAX_LABELS_PER_DOCUMENT = 10;
19602
19772
  var MAX_LABELS_MESSAGE = "A document can have at most 10 labels.";
19773
+ var MAX_SUGGESTED_LABELS = 30;
19774
+ var MAX_SUGGESTED_LABELS_MESSAGE = `A workspace can have at most ${MAX_SUGGESTED_LABELS} suggested labels.`;
19775
+ var SuggestedLabels = external_exports.array(DocumentLabel).max(MAX_SUGGESTED_LABELS, MAX_SUGGESTED_LABELS_MESSAGE);
19603
19776
  var PASSWORD_MIN_LENGTH = 4;
19604
19777
  var PASSWORD_MAX_LENGTH = 128;
19605
19778
  var TITLE_MAX_LENGTH = 512;
@@ -19662,7 +19835,19 @@ var DocumentRecord = external_exports.object({
19662
19835
  sizeBytes: external_exports.number().int().nonnegative(),
19663
19836
  expiresAt: external_exports.string().optional(),
19664
19837
  revokedAt: external_exports.string().optional(),
19665
- takedown: external_exports.object({ at: external_exports.string(), reason: external_exports.string(), reportId: Ulid.optional() }).optional(),
19838
+ takedown: external_exports.object({
19839
+ at: external_exports.string(),
19840
+ reason: external_exports.string(),
19841
+ reportId: Ulid.optional(),
19842
+ category: ReportReason.optional()
19843
+ }).optional(),
19844
+ legalHold: external_exports.object({
19845
+ at: external_exports.string(),
19846
+ by: external_exports.string(),
19847
+ reason: external_exports.string(),
19848
+ reportId: Ulid.optional(),
19849
+ until: external_exports.string().optional()
19850
+ }).optional(),
19666
19851
  passwordHash: external_exports.string().optional(),
19667
19852
  branding: DocumentBranding.optional(),
19668
19853
  labels: external_exports.array(external_exports.string()).optional(),
@@ -19820,6 +20005,7 @@ var PreferencesRecord = external_exports.object({
19820
20005
  cliConnectedAt: external_exports.string().optional(),
19821
20006
  ageConfirmedAt: external_exports.string().optional(),
19822
20007
  plusConfirmationSentFor: external_exports.string().optional(),
20008
+ signupCountedAt: external_exports.string().optional(),
19823
20009
  deletionRequestedAt: external_exports.string().optional(),
19824
20010
  suspendedAt: external_exports.string().nullable().default(null),
19825
20011
  suspendedReason: external_exports.string().nullable().default(null),
@@ -19900,7 +20086,9 @@ var GrantablePlan = external_exports.enum(["friends", "internal"]);
19900
20086
  var PlanLimits = external_exports.object({
19901
20087
  liveDocuments: external_exports.number(),
19902
20088
  maxDocumentBytes: external_exports.number(),
20089
+ storagePoolBytes: external_exports.number(),
19903
20090
  versionRetention: external_exports.union([external_exports.number(), external_exports.literal("all")]),
20091
+ versionRestore: external_exports.boolean(),
19904
20092
  rungs: external_exports.array(Exposure),
19905
20093
  linkControls: external_exports.boolean(),
19906
20094
  readerFooter: external_exports.boolean(),
@@ -19913,7 +20101,9 @@ var PLAN_LIMITS = {
19913
20101
  free: {
19914
20102
  liveDocuments: 10,
19915
20103
  maxDocumentBytes: 5242880,
20104
+ storagePoolBytes: 104857600,
19916
20105
  versionRetention: 5,
20106
+ versionRestore: false,
19917
20107
  rungs: ["private", "open"],
19918
20108
  linkControls: false,
19919
20109
  readerFooter: true,
@@ -19925,7 +20115,9 @@ var PLAN_LIMITS = {
19925
20115
  plus: {
19926
20116
  liveDocuments: 500,
19927
20117
  maxDocumentBytes: 20971520,
19928
- versionRetention: "all",
20118
+ storagePoolBytes: 5368709120,
20119
+ versionRetention: 100,
20120
+ versionRestore: true,
19929
20121
  rungs: ["private", "people", "password", "open"],
19930
20122
  linkControls: true,
19931
20123
  readerFooter: false,
@@ -19937,7 +20129,9 @@ var PLAN_LIMITS = {
19937
20129
  friends: {
19938
20130
  liveDocuments: 2000,
19939
20131
  maxDocumentBytes: 20971520,
19940
- versionRetention: "all",
20132
+ storagePoolBytes: 26843545600,
20133
+ versionRetention: 100,
20134
+ versionRestore: true,
19941
20135
  rungs: ["private", "people", "password", "open"],
19942
20136
  linkControls: true,
19943
20137
  readerFooter: false,
@@ -19949,7 +20143,9 @@ var PLAN_LIMITS = {
19949
20143
  internal: {
19950
20144
  liveDocuments: 10000,
19951
20145
  maxDocumentBytes: 20971520,
20146
+ storagePoolBytes: 107374182400,
19952
20147
  versionRetention: "all",
20148
+ versionRestore: true,
19953
20149
  rungs: ["private", "people", "password", "open"],
19954
20150
  linkControls: true,
19955
20151
  readerFooter: false,
@@ -19962,6 +20158,7 @@ var PLAN_LIMITS = {
19962
20158
  var PlanLimitName = external_exports.enum([
19963
20159
  "liveDocuments",
19964
20160
  "maxDocumentBytes",
20161
+ "storagePoolBytes",
19965
20162
  "versionRetention",
19966
20163
  "rungs",
19967
20164
  "linkControls",
@@ -19984,6 +20181,12 @@ function limitsFor(plan) {
19984
20181
  var HANDLE_MIN_LENGTH = 3;
19985
20182
  var HANDLE_MAX_LENGTH = 32;
19986
20183
  var HANDLE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
20184
+ var HANDLE_SHAPE = `[a-z0-9-]{${HANDLE_MIN_LENGTH},${HANDLE_MAX_LENGTH}}`;
20185
+ var PUBLIC_PATH_SHAPES = Object.freeze({
20186
+ collection: `^/${HANDLE_SHAPE}/c/[^/]+$`,
20187
+ document: `^/${HANDLE_SHAPE}/[^/]+$`,
20188
+ workspace: `^/${HANDLE_SHAPE}$`
20189
+ });
19987
20190
  var RESERVED_HANDLES = new Set([
19988
20191
  "app",
19989
20192
  "api",
@@ -20091,6 +20294,8 @@ var WorkspaceRecord = external_exports.object({
20091
20294
  handle: external_exports.string(),
20092
20295
  name: external_exports.string().min(1).max(WORKSPACE_NAME_MAX_LENGTH),
20093
20296
  branding: DocumentBranding.optional(),
20297
+ suggestedLabels: external_exports.array(external_exports.string()).optional(),
20298
+ suggestedLabelsOffer: external_exports.boolean().optional(),
20094
20299
  createdBy: external_exports.string(),
20095
20300
  createdAt: external_exports.string(),
20096
20301
  updatedAt: external_exports.string(),
@@ -20161,42 +20366,6 @@ var SaveRecord = external_exports.preprocess((raw) => {
20161
20366
  targetId: Ulid,
20162
20367
  savedAt: external_exports.string()
20163
20368
  }));
20164
- var ReportReason = external_exports.enum([
20165
- "spam",
20166
- "phishing",
20167
- "malware",
20168
- "copyright",
20169
- "illegal",
20170
- "harassment",
20171
- "other"
20172
- ]);
20173
- var ReportStatus = external_exports.enum(["open", "dismissed", "actioned"]);
20174
- var ReportTargetType = external_exports.enum(["document", "collection"]);
20175
- var REPORT_DETAILS_MAX_LENGTH = 2000;
20176
- var ReportRecord = external_exports.object({
20177
- id: Ulid,
20178
- targetType: external_exports.enum(["document", "collection", "url"]),
20179
- submittedUrl: external_exports.string().url().max(2048).optional(),
20180
- documentId: Ulid.optional(),
20181
- collectionId: Ulid.optional(),
20182
- workspaceId: Ulid.optional(),
20183
- handle: external_exports.string(),
20184
- slug: external_exports.string(),
20185
- version: external_exports.number().int().min(1).optional(),
20186
- reason: ReportReason,
20187
- details: external_exports.string().max(REPORT_DETAILS_MAX_LENGTH).optional(),
20188
- reporterUid: external_exports.string().optional(),
20189
- reporterEmail: external_exports.string().optional(),
20190
- reporterIpHash: external_exports.string().optional(),
20191
- createdAt: external_exports.string(),
20192
- status: ReportStatus,
20193
- resolvedAt: external_exports.string().optional(),
20194
- resolutionNote: external_exports.string().optional(),
20195
- alertedAt: external_exports.string().optional(),
20196
- digestedAt: external_exports.string().optional()
20197
- }).refine((report) => report.targetType === "url" ? report.submittedUrl !== void 0 && report.documentId === void 0 && report.collectionId === void 0 : report.workspaceId !== void 0 && (report.targetType === "document" ? report.documentId !== void 0 && report.collectionId === void 0 : report.collectionId !== void 0 && report.documentId === void 0), {
20198
- message: "A report names exactly one target: documentId for a document, collectionId for a collection."
20199
- });
20200
20369
  var ErrorCode = external_exports.enum([
20201
20370
  "validation_failed",
20202
20371
  "bad_request",
@@ -20257,6 +20426,8 @@ var WorkspaceResponse = external_exports.object({
20257
20426
  name: external_exports.string(),
20258
20427
  url: external_exports.string(),
20259
20428
  branding: DocumentBranding.optional(),
20429
+ suggestedLabels: external_exports.array(external_exports.string()).optional(),
20430
+ suggestedLabelsSeedable: external_exports.boolean().optional(),
20260
20431
  liveDocuments: external_exports.number().int().nonnegative(),
20261
20432
  collections: external_exports.number().int().nonnegative(),
20262
20433
  createdAt: external_exports.string(),
@@ -20268,7 +20439,19 @@ var WorkspaceResponse = external_exports.object({
20268
20439
  var MyWorkspacesResponse = external_exports.object({ items: external_exports.array(WorkspaceResponse) });
20269
20440
  var PatchWorkspaceRequest = external_exports.object({
20270
20441
  name: WorkspaceName.optional(),
20271
- branding: DocumentBranding.nullable().optional()
20442
+ branding: DocumentBranding.nullable().optional(),
20443
+ suggestedLabels: SuggestedLabels.optional(),
20444
+ expectedUpdatedAt: IsoInstant.optional()
20445
+ });
20446
+ var LabelUsage = external_exports.object({
20447
+ label: external_exports.string(),
20448
+ count: external_exports.number().int().nonnegative(),
20449
+ matchesCollection: external_exports.object({ slug: external_exports.string(), name: external_exports.string() }).optional()
20450
+ });
20451
+ var WorkspaceLabelsResponse = external_exports.object({
20452
+ suggested: external_exports.array(LabelUsage),
20453
+ other: external_exports.array(LabelUsage),
20454
+ seedable: external_exports.boolean().optional()
20272
20455
  });
20273
20456
  var DeleteWorkspaceResponse = external_exports.object({
20274
20457
  id: Ulid,
@@ -20369,7 +20552,8 @@ var HtmlLintCode = external_exports.enum([
20369
20552
  "fixed-position",
20370
20553
  "data-uri-image",
20371
20554
  "blocked-external-images",
20372
- "interactive-unsanitized"
20555
+ "interactive-unsanitized",
20556
+ "pdf_no_text"
20373
20557
  ]);
20374
20558
  var HtmlLintWarning = external_exports.object({
20375
20559
  code: HtmlLintCode,
@@ -20386,6 +20570,7 @@ var CreateDocumentResponse = external_exports.object({
20386
20570
  invitesFailed: external_exports.array(external_exports.string()).optional(),
20387
20571
  warnings: external_exports.array(HtmlLintWarning).optional()
20388
20572
  });
20573
+ var DocumentCollectionRef = external_exports.object({ slug: external_exports.string(), name: external_exports.string() });
20389
20574
  var ListDocumentsItem = external_exports.object({
20390
20575
  id: Ulid,
20391
20576
  can: CanList.optional(),
@@ -20403,6 +20588,7 @@ var ListDocumentsItem = external_exports.object({
20403
20588
  takenDown: external_exports.boolean().optional(),
20404
20589
  passwordProtected: external_exports.boolean().optional(),
20405
20590
  labels: external_exports.array(external_exports.string()).optional(),
20591
+ collections: external_exports.array(DocumentCollectionRef).optional(),
20406
20592
  unlisted: external_exports.boolean().optional(),
20407
20593
  deletedAt: external_exports.string().optional(),
20408
20594
  purgeAt: external_exports.string().optional(),
@@ -20425,6 +20611,7 @@ var ListDocumentsItem = external_exports.object({
20425
20611
  var ListDocumentsQuery = Pagination.extend({
20426
20612
  filter: external_exports.enum(["live", "trashed"]).default("live"),
20427
20613
  label: DocumentLabel.optional(),
20614
+ collection: SlugRef.optional(),
20428
20615
  sort: external_exports.enum(["updatedAt", "createdAt", "title"]).default("updatedAt")
20429
20616
  });
20430
20617
  var ListDocumentsResponse = page(ListDocumentsItem);
@@ -20468,6 +20655,7 @@ var OwnerDocumentResponse = DocumentRecord.omit({
20468
20655
  passwordProtected: external_exports.boolean().optional(),
20469
20656
  purgeAt: external_exports.string().optional(),
20470
20657
  awareness: EditAwareness.optional(),
20658
+ collections: external_exports.array(DocumentCollectionRef).optional(),
20471
20659
  followersRemoved: external_exports.number().int().positive().optional()
20472
20660
  });
20473
20661
  var PatchDocumentRequest = external_exports.object({
@@ -20704,6 +20892,28 @@ var SearchDocumentsResponse = external_exports.object({
20704
20892
  query: external_exports.string(),
20705
20893
  items: external_exports.array(SearchDocumentsItem)
20706
20894
  });
20895
+ var PublisherAppeal = ReportAppeal.pick({
20896
+ kind: true,
20897
+ status: true,
20898
+ at: true,
20899
+ restoreAfter: true,
20900
+ restoreBy: true,
20901
+ decidedAt: true,
20902
+ note: true
20903
+ });
20904
+ var DocumentAppealResponse = external_exports.object({
20905
+ takedown: external_exports.object({ at: external_exports.string(), reason: external_exports.string(), category: ReportReason.optional() }),
20906
+ appeal: PublisherAppeal.optional(),
20907
+ canAppeal: external_exports.boolean(),
20908
+ counterNoticeAllowed: external_exports.boolean()
20909
+ });
20910
+ var FileAppealRequest = external_exports.discriminatedUnion("kind", [
20911
+ external_exports.object({
20912
+ kind: external_exports.literal("appeal"),
20913
+ statement: external_exports.string().trim().min(1).max(APPEAL_STATEMENT_MAX_LENGTH)
20914
+ }),
20915
+ external_exports.object({ kind: external_exports.literal("counter_notice"), counterNotice: CounterNotice })
20916
+ ]);
20707
20917
  var OwnedSearchItem = SearchDocumentsItem.extend({
20708
20918
  handle: external_exports.string(),
20709
20919
  workspaceName: external_exports.string()
@@ -20877,12 +21087,14 @@ var GatedMetaResponse = external_exports.object({
20877
21087
  function isGatedMeta(meta3) {
20878
21088
  return "gate" in meta3;
20879
21089
  }
21090
+ var SignedRequestHeaders = external_exports.record(external_exports.string(), external_exports.string());
20880
21091
  var PublicContentResponse = external_exports.object({
20881
21092
  contentType: ContentType,
20882
21093
  version: external_exports.number().int().min(1),
20883
21094
  html: external_exports.string().optional(),
20884
21095
  data: external_exports.string().optional(),
20885
21096
  dataUrl: external_exports.string().optional(),
21097
+ dataHeaders: SignedRequestHeaders.optional(),
20886
21098
  mediaType: external_exports.string().optional(),
20887
21099
  viewOnly: external_exports.boolean().optional(),
20888
21100
  watermark: external_exports.boolean().optional(),
@@ -20938,6 +21150,7 @@ var InteractiveContentUrlResponse = external_exports.object({
20938
21150
  });
20939
21151
  var SourceDownloadResponse = external_exports.object({
20940
21152
  url: external_exports.string(),
21153
+ headers: SignedRequestHeaders.optional(),
20941
21154
  filename: external_exports.string(),
20942
21155
  expiresAt: external_exports.string()
20943
21156
  });
@@ -21013,7 +21226,8 @@ var ReaderSearchItem = external_exports.object({
21013
21226
  }).extend(ReaderItemMeta.shape);
21014
21227
  var ReaderSearchResponse = external_exports.object({
21015
21228
  query: external_exports.string(),
21016
- items: external_exports.array(ReaderSearchItem)
21229
+ items: external_exports.array(ReaderSearchItem),
21230
+ nextCursor: external_exports.string().optional()
21017
21231
  });
21018
21232
  var BrowseResponse = external_exports.object({
21019
21233
  documents: external_exports.array(CatalogDocumentItem),
@@ -21130,7 +21344,9 @@ var MeResponse = external_exports.object({
21130
21344
  plan: PlanId,
21131
21345
  pool: external_exports.object({
21132
21346
  liveDocuments: external_exports.number().int().nonnegative(),
21133
- limit: external_exports.number().int().positive()
21347
+ limit: external_exports.number().int().positive(),
21348
+ storageBytes: external_exports.number().int().nonnegative().optional(),
21349
+ storageLimit: external_exports.number().int().positive().optional()
21134
21350
  }),
21135
21351
  settings: SettingsResponse,
21136
21352
  workspaces: external_exports.array(WorkspaceResponse),
@@ -21311,7 +21527,9 @@ var UsageResponse = external_exports.object({
21311
21527
  limits: PlanLimits,
21312
21528
  pool: external_exports.object({
21313
21529
  liveDocuments: external_exports.number().int().nonnegative(),
21314
- limit: external_exports.number().int().positive()
21530
+ limit: external_exports.number().int().positive(),
21531
+ storageBytes: external_exports.number().int().nonnegative().optional(),
21532
+ storageLimit: external_exports.number().int().positive().optional()
21315
21533
  }),
21316
21534
  totals: external_exports.object({
21317
21535
  documents: external_exports.number().int().nonnegative(),
@@ -21349,7 +21567,11 @@ var CreateReportRequest = external_exports.object({
21349
21567
  details: external_exports.string().trim().max(2000).optional(),
21350
21568
  email: external_exports.email().optional()
21351
21569
  });
21352
- var CreateReportResponse = external_exports.object({ id: Ulid, createdAt: external_exports.string() });
21570
+ var CreateReportResponse = external_exports.object({
21571
+ id: Ulid,
21572
+ createdAt: external_exports.string(),
21573
+ statusUrl: external_exports.string().optional()
21574
+ });
21353
21575
  var HealthResponse = external_exports.object({ status: external_exports.literal("ok"), version: external_exports.string().optional() });
21354
21576
  var ReadinessCheck = external_exports.enum(["ok", "error"]);
21355
21577
  var ReadinessResponse = external_exports.object({
@@ -21501,8 +21723,8 @@ function plural2(n, word, pluralWord = `${word}s`) {
21501
21723
  function fields(...parts) {
21502
21724
  return parts.filter((p) => typeof p === "string" && p !== "").join(" ");
21503
21725
  }
21504
- function keyValueBlock(rows) {
21505
- return rows.filter((row2) => row2[1] !== void 0).map(([key, value]) => `${key}: ${value}`).join("\n");
21726
+ function keyValueBlock(rows2) {
21727
+ return rows2.filter((row2) => row2[1] !== void 0).map(([key, value]) => `${key}: ${value}`).join("\n");
21506
21728
  }
21507
21729
  function describeAwareness(awareness) {
21508
21730
  const parts = [`v${awareness.currentVersion}`];
@@ -21786,10 +22008,13 @@ async function readContent(path, type, fs = nodePublishFs) {
21786
22008
  function megabytes(bytes) {
21787
22009
  return `${bytes / 1048576} MB`;
21788
22010
  }
21789
- function assertWithinUploadLimit(path, sizeBytes) {
22011
+ function assertWithinUploadLimit(path, sizeBytes, contentType) {
21790
22012
  if (sizeBytes > MAX_UPLOAD_BYTES) {
21791
22013
  throw fileError(`${path} is too large to upload (${humanizeBytes(sizeBytes)}): the largest document is ${megabytes(MAX_UPLOAD_BYTES)}.`);
21792
22014
  }
22015
+ if (contentType === "markdown" && sizeBytes > MARKDOWN_MAX_BYTES) {
22016
+ throw fileError(`${path} is too large to upload (${humanizeBytes(sizeBytes)}): a Markdown document can be at most ${megabytes(MARKDOWN_MAX_BYTES)}. Split it, or publish it as HTML or PDF.`);
22017
+ }
21793
22018
  }
21794
22019
  var TITLE_MAX = 512;
21795
22020
  function decodeEntities(input2) {
@@ -21842,8 +22067,8 @@ var cachedVersion;
21842
22067
  function bundledVersion() {
21843
22068
  if (cachedVersion !== void 0)
21844
22069
  return cachedVersion;
21845
- if ("1.3.0".length > 0) {
21846
- cachedVersion = "1.3.0";
22070
+ if ("1.5.0".length > 0) {
22071
+ cachedVersion = "1.5.0";
21847
22072
  return cachedVersion;
21848
22073
  }
21849
22074
  try {
@@ -23729,10 +23954,11 @@ function createClient(options) {
23729
23954
  }
23730
23955
  return { status: response.status, data: result2.data, headers: response.headers, requestId };
23731
23956
  }
23732
- async function fetchSigned(url2, what = "source file") {
23957
+ async function fetchSigned(url2, what = "source file", headers = {}) {
23733
23958
  let response;
23734
23959
  try {
23735
23960
  response = await fetchImpl(url2, {
23961
+ headers: { ...headers },
23736
23962
  signal: AbortSignal.timeout(TIMEOUT_MS.signed)
23737
23963
  });
23738
23964
  }
@@ -23833,6 +24059,12 @@ function createClient(options) {
23833
24059
  schema: WorkspaceResponse,
23834
24060
  context: ws(handle, void 0, "workspace")
23835
24061
  }),
24062
+ getWorkspaceLabels: (handle) => call({
24063
+ method: "GET",
24064
+ path: `${W(handle)}/labels`,
24065
+ schema: WorkspaceLabelsResponse,
24066
+ context: ws(handle, void 0, "workspace")
24067
+ }),
23836
24068
  patchWorkspace: (handle, body) => call({
23837
24069
  method: "PATCH",
23838
24070
  path: W(handle),
@@ -23868,6 +24100,7 @@ function createClient(options) {
23868
24100
  filter: query?.filter,
23869
24101
  sort: query?.sort,
23870
24102
  label: query?.label,
24103
+ collection: query?.collection,
23871
24104
  ...listQuery(query)
23872
24105
  },
23873
24106
  schema: ListDocumentsResponse,
@@ -25038,12 +25271,15 @@ async function readTargets(options, fs = nodePublishFs) {
25038
25271
  assertNotWordDocument(file2);
25039
25272
  const contentType = options.contentType ?? inferContentType(file2);
25040
25273
  const { content, sizeBytes } = await readContent(file2, contentType, fs);
25041
- assertWithinUploadLimit(file2, sizeBytes);
25274
+ assertWithinUploadLimit(file2, sizeBytes, contentType);
25042
25275
  targets.push({ file: file2, contentType, content, sizeBytes });
25043
25276
  }
25044
25277
  return targets;
25045
25278
  }
25046
25279
  function lintHeader(warnings) {
25280
+ if (warnings.length > 0 && warnings.every((w) => w.code === "pdf_no_text")) {
25281
+ return "Published, with a note on search:";
25282
+ }
25047
25283
  return warnings.length === 1 && warnings[0]?.code === "interactive-unsanitized" ? "Published (interactive):" : "Published, but this HTML may render degraded in the reader:";
25048
25284
  }
25049
25285
  function printLintWarnings(ctx, warnings, prefix) {
@@ -25722,18 +25958,23 @@ async function emitBytes(bytes, options) {
25722
25958
  var USAGE = {
25723
25959
  list: buildUsage({
25724
25960
  synopsis: [
25725
- "handout list [--trashed] [--label <name>] [--sort updatedAt|createdAt|title] [--limit <n>] [--cursor <token>] [--all]"
25961
+ "handout list [--trashed] [--label <name>] [--collection <slug>] [--sort updatedAt|createdAt|title] [--limit <n>] [--cursor <token>] [--all]"
25726
25962
  ],
25727
25963
  description: "Lists the documents of the selected workspace.",
25728
25964
  flags: [
25729
25965
  ["--trashed", "List the trash instead of live documents"],
25730
- ["--label <name>", "Only documents carrying this label"],
25966
+ ["--label <name>", "Only documents carrying this label (what kind of document it is)"],
25967
+ ["--collection <slug>", "Only documents in this collection (what they belong to)"],
25731
25968
  ["--sort <key>", "updatedAt (default), createdAt or title"],
25732
25969
  ["--limit <n>", "Page size, 1-200"],
25733
25970
  ["--cursor <token>", "Continue from a previous page"],
25734
25971
  ["--all", "Walk every page"]
25735
25972
  ],
25736
- examples: ["handout list --label q3", "handout list --all --json"]
25973
+ examples: [
25974
+ "handout list --label report",
25975
+ "handout list --collection q3-launch",
25976
+ "handout list --all --json"
25977
+ ]
25737
25978
  }),
25738
25979
  get: buildUsage({
25739
25980
  synopsis: ["handout get <ref> [--password <secret>]"],
@@ -25868,7 +26109,7 @@ async function listDocuments(ctx) {
25868
26109
  const scanned = scanArgs(ctx.args, {
25869
26110
  context,
25870
26111
  usage: USAGE.list,
25871
- values: ["--label", "--sort", "--limit", "--cursor"],
26112
+ values: ["--label", "--collection", "--sort", "--limit", "--cursor"],
25872
26113
  booleans: ["--trashed", "--all"]
25873
26114
  });
25874
26115
  expectPositionals(scanned, context, 0);
@@ -25887,12 +26128,18 @@ async function listDocuments(ctx) {
25887
26128
  if (label !== void 0 && !DocumentLabel.safeParse(label).success) {
25888
26129
  throw usageError(`--label "${label}" must be 1-24 characters.`);
25889
26130
  }
26131
+ const collectionRaw = lastValue(scanned, "--collection")?.trim();
26132
+ const collection = collectionRaw === void 0 || collectionRaw === "" ? void 0 : collectionRaw;
26133
+ if (collection !== void 0 && !SlugRef.safeParse(collection).success) {
26134
+ throw usageError(`--collection "${collection}" is not a collection slug.`);
26135
+ }
25890
26136
  const trashed = scanned.seen.has("--trashed");
25891
26137
  const handle = await ctx.workspace();
25892
26138
  const client = await ctx.client();
25893
26139
  const query = {
25894
26140
  filter: trashed ? "trashed" : "live",
25895
26141
  ...label === void 0 ? {} : { label },
26142
+ ...collection === void 0 ? {} : { collection },
25896
26143
  ...sort === void 0 ? {} : { sort }
25897
26144
  };
25898
26145
  if (all) {
@@ -25915,7 +26162,7 @@ async function listDocuments(ctx) {
25915
26162
  });
25916
26163
  }
25917
26164
  function formatOwnerDocument(doc) {
25918
- const rows = [
26165
+ const rows2 = [
25919
26166
  ["title", doc.title],
25920
26167
  ["url", doc.url],
25921
26168
  ["slug", doc.slug],
@@ -25928,52 +26175,55 @@ function formatOwnerDocument(doc) {
25928
26175
  ];
25929
26176
  const when = (value) => value;
25930
26177
  if (doc.allowlist !== void 0 && doc.allowlist.length > 0) {
25931
- rows.push(["people", String(doc.allowlist.length)]);
26178
+ rows2.push(["people", String(doc.allowlist.length)]);
25932
26179
  }
25933
26180
  if (doc.passwordProtected === true)
25934
- rows.push(["password", "set"]);
25935
- rows.push(["expires", when(doc.expiresAt)]);
26181
+ rows2.push(["password", "set"]);
26182
+ rows2.push(["expires", when(doc.expiresAt)]);
25936
26183
  if (doc.maxViews !== void 0)
25937
- rows.push(["max views", `${doc.viewCount ?? 0} of ${doc.maxViews}`]);
25938
- rows.push(["revoked", when(doc.revokedAt)]);
26184
+ rows2.push(["max views", `${doc.viewCount ?? 0} of ${doc.maxViews}`]);
26185
+ rows2.push(["revoked", when(doc.revokedAt)]);
25939
26186
  if (doc.takedown !== void 0)
25940
- rows.push(["taken down", `${doc.takedown.at}: ${doc.takedown.reason}`]);
26187
+ rows2.push(["taken down", `${doc.takedown.at}: ${doc.takedown.reason}`]);
25941
26188
  if (doc.deletedAt !== void 0 || doc.trashed === true) {
25942
- rows.push(["trashed", doc.purgeAt === void 0 ? "yes" : `purge ${doc.purgeAt}`]);
26189
+ rows2.push(["trashed", doc.purgeAt === void 0 ? "yes" : `purge ${doc.purgeAt}`]);
25943
26190
  }
25944
26191
  if (doc.labels !== void 0 && doc.labels.length > 0)
25945
- rows.push(["labels", doc.labels.join(", ")]);
26192
+ rows2.push(["labels", doc.labels.join(", ")]);
26193
+ if (doc.collections !== void 0 && doc.collections.length > 0) {
26194
+ rows2.push(["collections", doc.collections.map((c) => `${c.name} (${c.slug})`).join(", ")]);
26195
+ }
25946
26196
  if (doc.unlisted === true)
25947
- rows.push(["unlisted", "yes"]);
26197
+ rows2.push(["unlisted", "yes"]);
25948
26198
  if (doc.interactive === true) {
25949
26199
  const connect = doc.interactiveConnectSrc ?? [];
25950
- rows.push([
26200
+ rows2.push([
25951
26201
  "interactive",
25952
26202
  connect.length === 0 ? "yes" : `yes (connect-src: ${connect.join(" ")})`
25953
26203
  ]);
25954
26204
  }
25955
26205
  if (doc.allowSourceDownload !== void 0) {
25956
- rows.push(["source download", doc.allowSourceDownload ? "allowed" : "off"]);
26206
+ rows2.push(["source download", doc.allowSourceDownload ? "allowed" : "off"]);
25957
26207
  }
25958
26208
  if (doc.allowExternalImages !== void 0) {
25959
- rows.push(["external images", doc.allowExternalImages ? "allowed" : "blocked"]);
26209
+ rows2.push(["external images", doc.allowExternalImages ? "allowed" : "blocked"]);
25960
26210
  }
25961
26211
  if (doc.requestAcknowledgment === true)
25962
- rows.push(["request ack", "yes"]);
26212
+ rows2.push(["request ack", "yes"]);
25963
26213
  if (doc.notifyOnView === true)
25964
- rows.push(["notify on view", "yes"]);
26214
+ rows2.push(["notify on view", "yes"]);
25965
26215
  if (doc.retainVersions !== void 0)
25966
- rows.push(["retain versions", String(doc.retainVersions)]);
26216
+ rows2.push(["retain versions", String(doc.retainVersions)]);
25967
26217
  if (doc.viewCount !== void 0)
25968
- rows.push(["views", String(doc.viewCount)]);
25969
- rows.push(["last viewed", when(doc.lastViewedAt)]);
26218
+ rows2.push(["views", String(doc.viewCount)]);
26219
+ rows2.push(["last viewed", when(doc.lastViewedAt)]);
25970
26220
  if (doc.awareness !== void 0)
25971
- rows.push(["editing", describeAwareness(doc.awareness)]);
25972
- return keyValueBlock(rows);
26221
+ rows2.push(["editing", describeAwareness(doc.awareness)]);
26222
+ return keyValueBlock(rows2);
25973
26223
  }
25974
26224
  function formatReaderDocument(meta3, host) {
25975
26225
  const provenance = meta3.provenance;
25976
- const rows = [
26226
+ const rows2 = [
25977
26227
  ["title", meta3.title],
25978
26228
  ["url", documentUrl(hostWithoutScheme(host), meta3.handle, meta3.slug)],
25979
26229
  [
@@ -25987,9 +26237,9 @@ function formatReaderDocument(meta3, host) {
25987
26237
  ["updated", provenance?.updatedAt]
25988
26238
  ];
25989
26239
  if (provenance !== void 0 && provenance.appearsIn.length > 0) {
25990
- rows.push(["appears in", provenance.appearsIn.map((c) => c.name).join(", ")]);
26240
+ rows2.push(["appears in", provenance.appearsIn.map((c) => c.name).join(", ")]);
25991
26241
  }
25992
- return keyValueBlock(rows);
26242
+ return keyValueBlock(rows2);
25993
26243
  }
25994
26244
  registerOutput("doc-get", {
25995
26245
  json: (data) => data.response,
@@ -26071,7 +26321,7 @@ ${SOURCE_HINT(slug)}`, {
26071
26321
  }
26072
26322
  throw err;
26073
26323
  }
26074
- const bytes = await client.fetchSigned(link.url, "source file");
26324
+ const bytes = await client.fetchSigned(link.url, "source file", link.headers);
26075
26325
  return emitBytes(bytes, {
26076
26326
  out,
26077
26327
  fallbackName: link.filename,
@@ -26116,7 +26366,7 @@ async function readCommand(ctx, writer = nodeWriteFile) {
26116
26366
  bytes = new Uint8Array(Buffer.from(content.data, "base64"));
26117
26367
  }
26118
26368
  else if (content.dataUrl !== void 0) {
26119
- bytes = await client.fetchSigned(content.dataUrl, "document");
26369
+ bytes = await client.fetchSigned(content.dataUrl, "document", content.dataHeaders);
26120
26370
  }
26121
26371
  else {
26122
26372
  bytes = new Uint8Array();
@@ -26559,7 +26809,7 @@ async function versionsSource(ctx, writer = nodeWriteFile) {
26559
26809
  const { handle, slug } = await resolveDocumentRef(ctx, ref);
26560
26810
  const client = await ctx.client();
26561
26811
  const link = await client.getVersionSource(handle, slug, version2);
26562
- const bytes = await client.fetchSigned(link.url, "version source");
26812
+ const bytes = await client.fetchSigned(link.url, "version source", link.headers);
26563
26813
  return emitBytes(bytes, {
26564
26814
  out,
26565
26815
  fallbackName: link.filename,
@@ -26616,7 +26866,7 @@ async function versionsDiff(ctx) {
26616
26866
  const client = await ctx.client();
26617
26867
  const [left, right] = await Promise.all([from, to].map(async (version2) => {
26618
26868
  const link = await client.getVersionSource(handle, slug, version2);
26619
- const bytes = await client.fetchSigned(link.url, "version source");
26869
+ const bytes = await client.fetchSigned(link.url, "version source", link.headers);
26620
26870
  return { filename: link.filename, bytes };
26621
26871
  }));
26622
26872
  if (left === void 0 || right === void 0)
@@ -26693,7 +26943,7 @@ var RESTORE_USAGE = buildUsage({
26693
26943
  examples: ["handout workspaces restore acme"]
26694
26944
  });
26695
26945
  var CONTEXT5 = (sub) => `on handout workspaces ${sub}`;
26696
- var DAY_MS = 86400000;
26946
+ var DAY_MS2 = 86400000;
26697
26947
  function parseName2(value, flag = "--name") {
26698
26948
  const name = value.trim();
26699
26949
  if (name === "")
@@ -26867,7 +27117,7 @@ async function runDelete2(ctx) {
26867
27117
  const explicit = scanned.positionals[0];
26868
27118
  requireAnswerable(ctx);
26869
27119
  const handle = await targetHandle(ctx, explicit);
26870
- const purgeOn = new Date(ctx.now().getTime() + 30 * DAY_MS).toISOString().slice(0, 10);
27120
+ const purgeOn = new Date(ctx.now().getTime() + 30 * DAY_MS2).toISOString().slice(0, 10);
26871
27121
  const confirmed = await ctx.confirm(`This schedules workspace "${handle}" and every document in it for deletion on ${purgeOn}. Type "y" to confirm: `);
26872
27122
  if (!confirmed)
26873
27123
  return result("cancelled", { message: "Deletion cancelled." });
@@ -27734,8 +27984,8 @@ function followingRow(item) {
27734
27984
  function recentRow(item) {
27735
27985
  return fields(item.targetType, item.url, item.title, `updated ${item.updatedAt}`, dormant(item));
27736
27986
  }
27737
- function section(title, rows) {
27738
- return [title, ...rows.length === 0 ? [" (none)"] : rows.map((row2) => ` ${row2}`)];
27987
+ function section(title, rows2) {
27988
+ return [title, ...rows2.length === 0 ? [" (none)"] : rows2.map((row2) => ` ${row2}`)];
27739
27989
  }
27740
27990
  function formatLibrary(response) {
27741
27991
  return [
@@ -27908,12 +28158,58 @@ var commands9 = {
27908
28158
  follow: { usage: FOLLOW_USAGE, run: runFollow },
27909
28159
  unfollow: { usage: UNFOLLOW_USAGE, run: runUnfollow }
27910
28160
  };
28161
+ var labels_exports = {};
28162
+ __export(labels_exports, {
28163
+ commands: () => commands10,
28164
+ formatLabels: () => formatLabels
28165
+ });
28166
+ var USAGE_TEXT = buildUsage({
28167
+ synopsis: ["handout labels"],
28168
+ description: "Shows the workspace's suggested labels with how many documents carry each, then any other labels in use. A label says what kind of document it is (plan, spec, report); a collection says what it belongs to. Pick from the suggested list and ask before inventing a label.",
28169
+ examples: ["handout labels", "handout labels --json"]
28170
+ });
28171
+ function rows(items) {
28172
+ const width = Math.max(0, ...items.map((item) => item.label.length));
28173
+ return items.map((item) => {
28174
+ const row2 = ` ${item.label.padEnd(width)} ${plural2(item.count, "document")}`;
28175
+ const match = item.matchesCollection;
28176
+ return match === void 0 ? row2 : `${row2} (all in collection "${match.name}" (${match.slug}); suggest the collection instead)`;
28177
+ });
28178
+ }
28179
+ function formatLabels(data) {
28180
+ const lines = [];
28181
+ if (data.suggested.length > 0) {
28182
+ lines.push("Suggested labels:", ...rows(data.suggested));
28183
+ }
28184
+ else if (data.seedable === true) {
28185
+ lines.push("No suggested labels yet. This workspace already uses labels, so none were added for you.", "Adopt the suggested set from the workspace's settings page.");
28186
+ }
28187
+ else {
28188
+ lines.push("No suggested labels.");
28189
+ }
28190
+ if (data.other.length > 0) {
28191
+ if (lines.length > 0)
28192
+ lines.push("");
28193
+ lines.push("Other labels in use (not suggested):", ...rows(data.other));
28194
+ }
28195
+ return lines.join("\n");
28196
+ }
28197
+ registerOutput("labels", passthrough(formatLabels));
28198
+ async function runLabels(ctx) {
28199
+ const context = "on handout labels";
28200
+ expectPositionals(scanArgs(ctx.args, { context, usage: USAGE_TEXT }), context, 0);
28201
+ const handle = await ctx.workspace();
28202
+ return result("labels", await (await ctx.client()).getWorkspaceLabels(handle));
28203
+ }
28204
+ var commands10 = {
28205
+ labels: { usage: USAGE_TEXT, run: runLabels }
28206
+ };
27911
28207
  var usage_exports = {};
27912
28208
  __export(usage_exports, {
27913
- commands: () => commands10,
28209
+ commands: () => commands11,
27914
28210
  formatUsage: () => formatUsage
27915
28211
  });
27916
- var USAGE_TEXT = buildUsage({
28212
+ var USAGE_TEXT2 = buildUsage({
27917
28213
  synopsis: ["handout usage"],
27918
28214
  description: "Shows your account's documents against its limit across all your workspaces, then storage per workspace and per document, biggest documents first.",
27919
28215
  examples: ["handout usage", "handout usage --json"]
@@ -27941,14 +28237,14 @@ function formatUsage(usage) {
27941
28237
  }
27942
28238
  async function runUsage(ctx) {
27943
28239
  const context = "on handout usage";
27944
- expectPositionals(scanArgs(ctx.args, { context, usage: USAGE_TEXT }), context, 0);
28240
+ expectPositionals(scanArgs(ctx.args, { context, usage: USAGE_TEXT2 }), context, 0);
27945
28241
  if (ctx.global.workspace !== void 0)
27946
28242
  throw usageError(WORKSPACE_REFUSED);
27947
28243
  return result("usage", await (await ctx.client()).getUsage());
27948
28244
  }
27949
28245
  registerOutput("usage", { json: (data) => data, text: formatUsage });
27950
- var commands10 = {
27951
- usage: { usage: USAGE_TEXT, run: runUsage }
28246
+ var commands11 = {
28247
+ usage: { usage: USAGE_TEXT2, run: runUsage }
27952
28248
  };
27953
28249
  var skill_exports = {};
27954
28250
  __export(skill_exports, {
@@ -27956,7 +28252,7 @@ __export(skill_exports, {
27956
28252
  SKILL_AGENTS: () => SKILL_AGENTS,
27957
28253
  SKILL_FOLDER: () => SKILL_FOLDER,
27958
28254
  agentSkillsDir: () => agentSkillsDir,
27959
- commands: () => commands11,
28255
+ commands: () => commands12,
27960
28256
  packagedSkillPath: () => packagedSkillPath
27961
28257
  });
27962
28258
  import { randomBytes as randomBytes3 } from "node:crypto";
@@ -27993,7 +28289,7 @@ function packagedSkillPath(env, moduleUrl = import.meta.url) {
27993
28289
  if (override !== void 0 && override !== "")
27994
28290
  return resolve(override);
27995
28291
  const here = dirname2(fileURLToPath(moduleUrl));
27996
- const bundled = "1.3.0".length > 0;
28292
+ const bundled = "1.5.0".length > 0;
27997
28293
  return bundled ? join4(here, "SKILL.md") : join4(here, "..", "..", "SKILL.md");
27998
28294
  }
27999
28295
  var INSTALL_USAGE = buildUsage({
@@ -28129,7 +28425,7 @@ ${INSTALL_USAGE}`);
28129
28425
  };
28130
28426
  return result("skill-install", data);
28131
28427
  }
28132
- var commands11 = {
28428
+ var commands12 = {
28133
28429
  "skill install": { usage: INSTALL_USAGE, run: runSkillInstall }
28134
28430
  };
28135
28431
  import { realpathSync } from "node:fs";
@@ -28281,6 +28577,7 @@ var COMMAND_TREE = {
28281
28577
  acks: { modules: ["documents", "manage"], summary: "Show who acknowledged a document" },
28282
28578
  list: { modules: ["documents"], summary: "List your documents" },
28283
28579
  get: { modules: ["documents"], summary: "Show a document's details" },
28580
+ labels: { modules: ["labels"], summary: "Show the suggested labels and how often each is used" },
28284
28581
  search: { modules: ["documents"], summary: "Search your documents" },
28285
28582
  source: { modules: ["documents"], summary: "Download a document's source" },
28286
28583
  open: { modules: ["documents"], summary: "Print (or open) a document's link" },
@@ -28362,14 +28659,14 @@ var COMMAND_TREE = {
28362
28659
  help: { modules: [], summary: "Show help for a command" }
28363
28660
  };
28364
28661
  function buildGlobalUsage() {
28365
- const rows = GLOBAL_FLAGS.map((f) => [
28662
+ const rows2 = GLOBAL_FLAGS.map((f) => [
28366
28663
  `${f.alias === void 0 ? "" : `${f.alias}, `}${f.flag}${f.value === void 0 ? "" : ` ${f.value}`}`,
28367
28664
  f.description
28368
28665
  ]);
28369
- rows.push(["--version", "Print the CLI version"]);
28370
- const width = Math.max(...rows.map(([label]) => label.length));
28666
+ rows2.push(["--version", "Print the CLI version"]);
28667
+ const width = Math.max(...rows2.map(([label]) => label.length));
28371
28668
  const lines = ["Usage: handout <command> [subcommand] [args] [flags]", "", "Global flags:"];
28372
- for (const [label, description] of rows)
28669
+ for (const [label, description] of rows2)
28373
28670
  lines.push(` ${label.padEnd(width)} ${description}`);
28374
28671
  lines.push("", "Commands:");
28375
28672
  const names = Object.entries(COMMAND_TREE).filter(([, entry]) => entry.deferred !== true);
@@ -28414,6 +28711,8 @@ async function importModule(name) {
28414
28711
  return Promise.resolve(auth_exports);
28415
28712
  case "library":
28416
28713
  return Promise.resolve(library_exports);
28714
+ case "labels":
28715
+ return Promise.resolve(labels_exports);
28417
28716
  case "usage":
28418
28717
  return Promise.resolve(usage_exports);
28419
28718
  case "skill":
@@ -28579,7 +28878,7 @@ function createContext(command, args, global, host, deps) {
28579
28878
  };
28580
28879
  }
28581
28880
  async function familyUsage(name, entry, deps) {
28582
- const rows = [];
28881
+ const rows2 = [];
28583
28882
  for (const moduleName of entry.modules) {
28584
28883
  const mod = await loadCommandModule(moduleName, deps);
28585
28884
  if (mod === void 0)
@@ -28588,14 +28887,14 @@ async function familyUsage(name, entry, deps) {
28588
28887
  if (!key.startsWith(`${name} `))
28589
28888
  continue;
28590
28889
  const first = def.usage.split("\n")[0]?.replace(/^Usage:\s*/, "") ?? key;
28591
- rows.push(` ${first}`);
28890
+ rows2.push(` ${first}`);
28592
28891
  }
28593
28892
  }
28594
28893
  return [
28595
28894
  `Usage: handout ${name} <subcommand> [args] [flags]`,
28596
28895
  "",
28597
28896
  "Subcommands:",
28598
- ...rows,
28897
+ ...rows2,
28599
28898
  "",
28600
28899
  `Run handout ${name} <subcommand> --help for that subcommand's flags.`
28601
28900
  ].join("\n");
@@ -28682,8 +28981,7 @@ async function runCommand(argv, deps = defaultDeps()) {
28682
28981
  function printLintWarnings2(ctx, warnings, prefix) {
28683
28982
  if (ctx.json || warnings === void 0 || warnings.length === 0)
28684
28983
  return;
28685
- const only = warnings.length === 1 ? warnings[0] : void 0;
28686
- const header = only?.code === "interactive-unsanitized" ? "Published (interactive):" : "Published, but this HTML may render degraded in the reader:";
28984
+ const header = lintHeader(warnings);
28687
28985
  const lines = warnings.map((w) => ` - ${w.message}`);
28688
28986
  if (prefix !== void 0)
28689
28987
  ctx.warn(`${prefix}:`, header, ...lines);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@usehandout/cli",
3
- "version": "1.3.0",
3
+ "version": "1.5.0",
4
4
  "description": "The handout command: publish HTML, Markdown and PDF files as Handout links, and the agent skill that lets Claude Code, Codex and other agents do it.",
5
5
  "keywords": [
6
6
  "handout",