@owlmeans/llm-reader-google-drive 0.0.0-stage → 0.2.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 (90) hide show
  1. package/README.md +113 -2
  2. package/agent-meta/manifest.json +16 -0
  3. package/agent-meta/skills/llm-reader-google-drive/SKILL.md +131 -0
  4. package/build/consts.d.ts +45 -0
  5. package/build/consts.d.ts.map +1 -0
  6. package/build/consts.js +54 -0
  7. package/build/consts.js.map +1 -0
  8. package/build/consts.local.d.ts +3 -0
  9. package/build/consts.local.d.ts.map +1 -0
  10. package/build/consts.local.js +3 -0
  11. package/build/consts.local.js.map +1 -0
  12. package/build/errors.d.ts +14 -0
  13. package/build/errors.d.ts.map +1 -0
  14. package/build/errors.js +26 -0
  15. package/build/errors.js.map +1 -0
  16. package/build/index.d.ts +6 -0
  17. package/build/index.d.ts.map +1 -0
  18. package/build/index.js +5 -0
  19. package/build/index.js.map +1 -0
  20. package/build/source/api.d.ts +9 -0
  21. package/build/source/api.d.ts.map +1 -0
  22. package/build/source/api.js +80 -0
  23. package/build/source/api.js.map +1 -0
  24. package/build/source/consts.local.d.ts +33 -0
  25. package/build/source/consts.local.d.ts.map +1 -0
  26. package/build/source/consts.local.js +39 -0
  27. package/build/source/consts.local.js.map +1 -0
  28. package/build/source/embedded.d.ts +10 -0
  29. package/build/source/embedded.d.ts.map +1 -0
  30. package/build/source/embedded.js +82 -0
  31. package/build/source/embedded.js.map +1 -0
  32. package/build/source/http.d.ts +6 -0
  33. package/build/source/http.d.ts.map +1 -0
  34. package/build/source/http.js +61 -0
  35. package/build/source/http.js.map +1 -0
  36. package/build/source/probe.d.ts +10 -0
  37. package/build/source/probe.d.ts.map +1 -0
  38. package/build/source/probe.js +80 -0
  39. package/build/source/probe.js.map +1 -0
  40. package/build/source/types.local.d.ts +87 -0
  41. package/build/source/types.local.d.ts.map +1 -0
  42. package/build/source/types.local.js +2 -0
  43. package/build/source/types.local.js.map +1 -0
  44. package/build/source.d.ts +22 -0
  45. package/build/source.d.ts.map +1 -0
  46. package/build/source.js +169 -0
  47. package/build/source.js.map +1 -0
  48. package/build/types.d.ts +79 -0
  49. package/build/types.d.ts.map +1 -0
  50. package/build/types.js +2 -0
  51. package/build/types.js.map +1 -0
  52. package/build/url/consts.local.d.ts +10 -0
  53. package/build/url/consts.local.d.ts.map +1 -0
  54. package/build/url/consts.local.js +15 -0
  55. package/build/url/consts.local.js.map +1 -0
  56. package/build/url.d.ts +8 -0
  57. package/build/url.d.ts.map +1 -0
  58. package/build/url.js +117 -0
  59. package/build/url.js.map +1 -0
  60. package/build/utils/names/types.d.ts +10 -0
  61. package/build/utils/names/types.d.ts.map +1 -0
  62. package/build/utils/names/types.js +2 -0
  63. package/build/utils/names/types.js.map +1 -0
  64. package/build/utils/names.d.ts +4 -0
  65. package/build/utils/names.d.ts.map +1 -0
  66. package/build/utils/names.js +31 -0
  67. package/build/utils/names.js.map +1 -0
  68. package/package.json +62 -4
  69. package/src/consts.local.ts +2 -0
  70. package/src/consts.ts +60 -0
  71. package/src/errors.ts +30 -0
  72. package/src/index.ts +7 -0
  73. package/src/source/api.ts +81 -0
  74. package/src/source/consts.local.ts +52 -0
  75. package/src/source/embedded.ts +83 -0
  76. package/src/source/http.ts +66 -0
  77. package/src/source/probe.ts +84 -0
  78. package/src/source/types.local.ts +91 -0
  79. package/src/source.ts +179 -0
  80. package/src/types.ts +86 -0
  81. package/src/url/consts.local.ts +19 -0
  82. package/src/url.ts +121 -0
  83. package/src/utils/names/types.ts +9 -0
  84. package/src/utils/names.ts +36 -0
  85. package/tests/context.ts +212 -0
  86. package/tests/fixtures.ts +88 -0
  87. package/tests/live.spec.ts +53 -0
  88. package/tests/source.spec.ts +189 -0
  89. package/tests/tsconfig.json +12 -0
  90. package/tsconfig.json +16 -0
package/src/source.ts ADDED
@@ -0,0 +1,179 @@
1
+ import type { ReaderSource, ReaderSourceContext, SourceEntry } from '@owlmeans/llm-reader'
2
+ import { logger } from '@owlmeans/log'
3
+ import {
4
+ DEFAULT_GOOGLE_DRIVE_DEPTH, DEFAULT_GOOGLE_DRIVE_MAX_ENTRIES, DEFAULT_GOOGLE_DRIVE_MAX_FOLDERS, GOOGLE_DRIVE_SOURCE, GoogleDriveFailure,
5
+ GoogleDriveKind,
6
+ } from './consts.js'
7
+ import { GoogleDriveError } from './errors.js'
8
+ import { DRIVE_PROBE_CONCURRENCY, DRIVE_SCAN_LIMIT_BYTES, LOG_SCOPE } from './source/consts.local.js'
9
+ import { makeApiLister } from './source/api.js'
10
+ import { makeEmbeddedLister } from './source/embedded.js'
11
+ import { makeDriveHttp } from './source/http.js'
12
+ import { makeDriveProbe } from './source/probe.js'
13
+ import type { DriveFolder, DriveItem, DriveLister, DriveProbe, ResolvedLink } from './source/types.local.js'
14
+ import type { GoogleDriveSourceOptions, GoogleEditorKind } from './types.js'
15
+ import { createGoogleDriveUrlHelper } from './url.js'
16
+ import { nameUtils } from './utils/names.js'
17
+
18
+ const log = logger(LOG_SCOPE)
19
+
20
+ /** Run `work` over `items`, at most `width` at once, keeping their order. */
21
+ const pooled = async <T, R>(items: T[], width: number, work: (item: T) => Promise<R>): Promise<R[]> => {
22
+ const results = new Array<R>(items.length)
23
+ let next = 0
24
+ const worker = async (): Promise<void> => {
25
+ while (next < items.length) {
26
+ const index = next++
27
+ results[index] = await work(items[index]!)
28
+ }
29
+ }
30
+ await Promise.all(Array.from({ length: Math.min(width, items.length) }, worker))
31
+ return results
32
+ }
33
+
34
+ /**
35
+ * Google Drive as a reader source — public folder, file and Docs links expanded into entries the
36
+ * collector downloads with a plain GET:
37
+ *
38
+ * - a folder (`drive/folders/<id>`, `open?id=` of a folder) is listed breadth-first down to `depth`
39
+ * sub-folder levels, at most `maxEntries` entries (and the collect's `maxFiles + 1`, so the cut is
40
+ * reported) from at most `maxFolders` folders — keyless from the embedded folder view, or through
41
+ * Drive API v3 with `apiKey`; entry paths are `<sub-folder>/<name>` relative to the linked folder;
42
+ * - a stored file becomes its usercontent download (`confirm=t`); a file whose size is unknown or
43
+ * past Drive's scan limit is probed first (one ranged GET) for its name, size and — behind Drive's
44
+ * warning form — the URL that really serves the bytes; a file Drive refuses is left out and logged;
45
+ * - an editor file (Docs, Sheets, Slides, Drawings) becomes its export in the configured format, its
46
+ * name with that extension;
47
+ * - a single file or editor link is one entry named as Drive names it (`Content-Disposition`).
48
+ *
49
+ * A private item throws `GoogleDriveError` (`not-public`), an exhausted quota `quota`, a 404
50
+ * `not-found`. Every request is the reader's guarded fetch, under its timeout and the collect's signal.
51
+ */
52
+ export const createGoogleDriveSource = (options: GoogleDriveSourceOptions = {}): ReaderSource => {
53
+ const urls = createGoogleDriveUrlHelper(options)
54
+ const depth = Math.max(0, Math.floor(options.depth ?? DEFAULT_GOOGLE_DRIVE_DEPTH))
55
+ const maxEntries = Math.max(1, Math.floor(options.maxEntries ?? DEFAULT_GOOGLE_DRIVE_MAX_ENTRIES))
56
+ const maxFolders = Math.max(1, Math.floor(options.maxFolders ?? DEFAULT_GOOGLE_DRIVE_MAX_FOLDERS))
57
+ const apiKey = options.apiKey != null && options.apiKey.trim() !== '' ? options.apiKey.trim() : undefined
58
+
59
+ const matches: ReaderSource['matches'] = url => urls.parse(url) != null
60
+
61
+ // A link nothing matched that landed on Drive (a shortener, a redirecting page) is taken by where it landed.
62
+ const recognizes: NonNullable<ReaderSource['recognizes']> = async answer => matches(answer.finalUrl)
63
+
64
+ const aborted = (context: ReaderSourceContext): boolean => context.signal?.aborted === true
65
+
66
+ const editorEntry = (path: string, kind: GoogleEditorKind, id: string, name: string): SourceEntry => {
67
+ const exported = urls.exportOf(kind, id)
68
+ const named = nameUtils.withExtension(nameUtils.segment(name), exported.extension)
69
+ return { path: `${path}${named}`, url: exported.url, name: named }
70
+ }
71
+
72
+ /** A listed file as an entry — probed unless its size is known and below the scan limit (or over the collect's cap). */
73
+ const fileEntry = async (path: string, item: DriveItem, probe: DriveProbe, context: ReaderSourceContext): Promise<SourceEntry | undefined> => {
74
+ const name = nameUtils.segment(item.name)
75
+ const plain: SourceEntry = {
76
+ path: `${path}${name}`, url: urls.downloadUrl(item.id, item.resourceKey), name,
77
+ ...(item.size != null ? { size: item.size } : {}), ...(item.mime != null ? { mime: item.mime } : {}),
78
+ }
79
+ if (item.size != null && (item.size < DRIVE_SCAN_LIMIT_BYTES || item.size > context.limits.maxFileBytes)) return plain
80
+ try {
81
+ const probed = await probe.file(item.id, item.resourceKey)
82
+ return { ...plain, url: probed.url, ...(probed.size != null ? { size: probed.size } : {}) }
83
+ } catch (error) {
84
+ if (aborted(context)) throw error
85
+ if (error instanceof GoogleDriveError) {
86
+ log.warn('A Drive file was left out', { file: item.id, reason: error.reason })
87
+ return undefined
88
+ }
89
+ // A probe that failed on the wire leaves the download to the collector, which reports its own outcome.
90
+ log.debug('A Drive file was not probed', { file: item.id, error })
91
+ return plain
92
+ }
93
+ }
94
+
95
+ const walk = async (root: ResolvedLink, lister: DriveLister, probe: DriveProbe, context: ReaderSourceContext): Promise<SourceEntry[]> => {
96
+ const wanted = Math.min(maxEntries, context.limits.maxFiles + 1)
97
+ const queue: DriveFolder[] = [{ id: root.id, ...(root.resourceKey != null ? { resourceKey: root.resourceKey } : {}), prefix: '', level: 0 }]
98
+ const seen = new Set<string>([root.id])
99
+ const found: Array<{ path: string, item: DriveItem }> = []
100
+ const cut = { folders: 0, depth: 0, entries: false }
101
+ let listed = 0
102
+ while (queue.length > 0 && found.length < wanted) {
103
+ if (listed >= maxFolders) {
104
+ cut.folders = queue.length
105
+ break
106
+ }
107
+ const folder = queue.shift()!
108
+ let items: DriveItem[]
109
+ try {
110
+ items = await lister.list(folder, wanted - found.length)
111
+ } catch (error) {
112
+ if (folder.level === 0 || aborted(context)) throw error
113
+ log.warn('A Drive sub-folder was not listed', { folder: folder.id, error })
114
+ continue
115
+ } finally {
116
+ listed++
117
+ }
118
+ for (const item of items) {
119
+ if (item.kind === GoogleDriveKind.Folder) {
120
+ if (seen.has(item.id)) continue
121
+ seen.add(item.id)
122
+ if (folder.level >= depth) {
123
+ cut.depth++
124
+ continue
125
+ }
126
+ queue.push({
127
+ id: item.id, ...(item.resourceKey != null ? { resourceKey: item.resourceKey } : {}),
128
+ prefix: `${folder.prefix}${nameUtils.segment(item.name)}/`, level: folder.level + 1,
129
+ })
130
+ continue
131
+ }
132
+ if (found.length >= wanted) {
133
+ cut.entries = true
134
+ break
135
+ }
136
+ found.push({ path: folder.prefix, item })
137
+ }
138
+ }
139
+ if (queue.length > 0 && found.length >= wanted) cut.entries = true
140
+ if (cut.entries || cut.folders > 0 || cut.depth > 0) {
141
+ log.warn('A Drive folder was cut', { folder: root.id, entries: found.length, wanted, folders: cut.folders, belowDepth: cut.depth })
142
+ }
143
+ const entries = await pooled(found, DRIVE_PROBE_CONCURRENCY, async ({ path, item }) =>
144
+ item.kind === GoogleDriveKind.File
145
+ ? await fileEntry(path, item, probe, context)
146
+ : editorEntry(path, item.kind as GoogleEditorKind, item.id, item.name),
147
+ )
148
+ const kept = entries.filter((entry): entry is SourceEntry => entry != null)
149
+ log.debug('Expanded a Drive folder', { folder: root.id, folders: listed, entries: kept.length })
150
+ return kept
151
+ }
152
+
153
+ const single = async (target: ResolvedLink, probe: DriveProbe): Promise<SourceEntry[]> => {
154
+ if (target.kind === GoogleDriveKind.File) {
155
+ const probed = await probe.file(target.id, target.resourceKey)
156
+ const name = nameUtils.segment(probed.name ?? target.name ?? target.id)
157
+ return [{
158
+ path: name, url: probed.url, name, ...(probed.size != null ? { size: probed.size } : target.size != null ? { size: target.size } : {}),
159
+ ...(target.mime != null ? { mime: target.mime } : {}),
160
+ }]
161
+ }
162
+ const kind = target.kind as GoogleEditorKind
163
+ const probed = await probe.exported(urls.exportOf(kind, target.id).url)
164
+ const named = editorEntry('', kind, target.id, probed.name ?? target.name ?? target.id)
165
+ return [{ ...named, url: probed.url }]
166
+ }
167
+
168
+ const expand: ReaderSource['expand'] = async (url, context) => {
169
+ const link = urls.parse(url)
170
+ if (link == null) throw new GoogleDriveError(GoogleDriveFailure.NotALink)
171
+ const http = makeDriveHttp(context, urls)
172
+ const lister = apiKey != null ? makeApiLister(http, urls, apiKey) : makeEmbeddedLister(http, urls)
173
+ const probe = makeDriveProbe(http, urls)
174
+ const target: ResolvedLink = link.kind === GoogleDriveKind.Unresolved ? await lister.resolve(url, link) : link
175
+ return target.kind === GoogleDriveKind.Folder ? await walk(target, lister, probe, context) : await single(target, probe)
176
+ }
177
+
178
+ return { name: GOOGLE_DRIVE_SOURCE, matches, recognizes, expand }
179
+ }
package/src/types.ts ADDED
@@ -0,0 +1,86 @@
1
+ import type { GoogleDriveKind } from './consts.js'
2
+
3
+ /** The format each Google editor file exports as. */
4
+ export interface GoogleExportFormats {
5
+ /** Docs: `docx` (default), `pdf`, `odt`, `rtf`, `txt`, `epub`, `md`, or `html` (a zip). */
6
+ document?: 'docx' | 'pdf' | 'odt' | 'rtf' | 'txt' | 'epub' | 'md' | 'html'
7
+ /** Sheets: `xlsx` (default), `ods`, `pdf`, `csv` or `tsv` (the first sheet). */
8
+ spreadsheet?: 'xlsx' | 'ods' | 'pdf' | 'csv' | 'tsv'
9
+ /** Slides: `pptx` (default), `odp`, `pdf` or `txt`. */
10
+ presentation?: 'pptx' | 'odp' | 'pdf' | 'txt'
11
+ /** Drawings: `png` (default), `svg`, `pdf` or `jpg`. */
12
+ drawing?: 'png' | 'svg' | 'pdf' | 'jpg'
13
+ }
14
+
15
+ export interface GoogleDriveUrlOptions {
16
+ /** Where Google answers; tests point these at a stand-in. */
17
+ origins?: GoogleDriveOrigins
18
+ /** Export formats of Docs, Sheets, Slides and Drawings. */
19
+ exports?: GoogleExportFormats
20
+ }
21
+
22
+ /** Every one is an origin (`https://host[:port]`); links match its host over http or https. */
23
+ export interface GoogleDriveOrigins {
24
+ drive?: string
25
+ usercontent?: string
26
+ docs?: string
27
+ accounts?: string
28
+ /** The Drive API (`/drive/v3/files`), used only with an `apiKey`. */
29
+ api?: string
30
+ }
31
+
32
+ export interface GoogleDriveSourceOptions extends GoogleDriveUrlOptions {
33
+ /**
34
+ * A Google API key with the Drive API enabled: folders are listed through Drive API v3 (pages,
35
+ * sizes, media types, shortcuts) instead of the keyless embedded folder view. Sent as the
36
+ * `X-Goog-Api-Key` header — never in a URL.
37
+ */
38
+ apiKey?: string
39
+ /** Sub-folder levels listed below the linked folder; `0` lists its own files only. Default 3. */
40
+ depth?: number
41
+ /** Entries one link expands to at most (the collect's `maxFiles + 1` caps it too). Default 200. */
42
+ maxEntries?: number
43
+ /** Folders one link lists at most — each costs a request. Default 50. */
44
+ maxFolders?: number
45
+ }
46
+
47
+ /** A Drive or Docs link as read from its URL alone. */
48
+ export interface GoogleDriveLink {
49
+ kind: GoogleDriveKind
50
+ id: string
51
+ /** The `resourcekey` of a link shared before Drive's 2021 security update. */
52
+ resourceKey?: string
53
+ }
54
+
55
+ /** Google editor files — the kinds that are exported, not downloaded. */
56
+ export type GoogleEditorKind = GoogleDriveKind.Document | GoogleDriveKind.Spreadsheet | GoogleDriveKind.Presentation | GoogleDriveKind.Drawing
57
+
58
+ /** An editor file's export: where its bytes come from and the extension its name takes. */
59
+ export interface GoogleExport {
60
+ url: string
61
+ extension: string
62
+ }
63
+
64
+ /** Drive and Docs URLs read and built, against the configured origins. */
65
+ export interface GoogleDriveUrlHelper {
66
+ /**
67
+ * What a link points at: `drive/folders/<id>` (also `/drive/u/<n>/…`, `folderview`,
68
+ * `embeddedfolderview`), `file/d/<id>`, `uc?id=`, a usercontent download, `open?id=` (unresolved),
69
+ * `docs.google.com/{document,spreadsheets,presentation,drawings}/d/<id>` — `undefined` for anything else.
70
+ */
71
+ parse: (url: string) => GoogleDriveLink | undefined
72
+ /** The direct bytes of a stored file — the large-file warning already confirmed (`confirm=t`). */
73
+ downloadUrl: (id: string, resourceKey?: string) => string
74
+ /** An editor file's export in the configured format. */
75
+ exportOf: (kind: GoogleEditorKind, id: string) => GoogleExport
76
+ /** The keyless, static listing page of a folder. */
77
+ folderViewUrl: (id: string, resourceKey?: string) => string
78
+ /** A Drive API v3 page of a folder's children. */
79
+ apiListUrl: (folderId: string, pageToken?: string) => string
80
+ /** A Drive API v3 item's metadata. */
81
+ apiFileUrl: (id: string) => string
82
+ /** Whether a URL is Google's sign-in host. */
83
+ isSignIn: (url: string) => boolean
84
+ /** Whether a URL is served by Drive itself — drive, usercontent or docs. */
85
+ owns: (url: string) => boolean
86
+ }
@@ -0,0 +1,19 @@
1
+ import { GoogleDriveKind } from '../consts.js'
2
+ import type { GoogleEditorKind } from '../types.js'
3
+
4
+ /** The Docs path segment of each editor kind. */
5
+ export const EDITOR_PATHS: Readonly<Record<string, GoogleEditorKind>> = Object.freeze({
6
+ document: GoogleDriveKind.Document,
7
+ spreadsheets: GoogleDriveKind.Spreadsheet,
8
+ presentation: GoogleDriveKind.Presentation,
9
+ drawings: GoogleDriveKind.Drawing,
10
+ })
11
+
12
+ /** An export format whose file extension differs from its name — Docs' web page export is a zip. */
13
+ export const EXPORT_EXTENSIONS: Readonly<Record<string, string>> = Object.freeze({ html: 'zip' })
14
+
15
+ /** The Drive API fields of one listed child. */
16
+ export const DRIVE_API_ITEM_FIELDS = 'id,name,mimeType,size,resourceKey,shortcutDetails(targetId,targetMimeType,targetResourceKey)'
17
+
18
+ /** Children per Drive API page (the API's maximum). */
19
+ export const DRIVE_API_PAGE_SIZE = 1000
package/src/url.ts ADDED
@@ -0,0 +1,121 @@
1
+ import { DEFAULT_GOOGLE_DRIVE_ORIGINS, DEFAULT_GOOGLE_EXPORTS, GoogleDriveKind } from './consts.js'
2
+ import type { GoogleDriveLink, GoogleDriveUrlHelper, GoogleDriveUrlOptions } from './types.js'
3
+ import { DRIVE_ID_PATTERN } from './consts.local.js'
4
+ import { DRIVE_API_ITEM_FIELDS, DRIVE_API_PAGE_SIZE, EDITOR_PATHS, EXPORT_EXTENSIONS } from './url/consts.local.js'
5
+
6
+ /**
7
+ * Drive and Docs links read from the URL alone, and the URLs the source asks Google: the direct
8
+ * usercontent download (`confirm=t`), editor exports in the configured formats, the keyless embedded
9
+ * folder view and Drive API v3. Links match the configured hosts over http or https.
10
+ */
11
+ export const createGoogleDriveUrlHelper = (options: GoogleDriveUrlOptions = {}): GoogleDriveUrlHelper => {
12
+ const origins = { ...DEFAULT_GOOGLE_DRIVE_ORIGINS, ...options.origins }
13
+ const formats = { ...DEFAULT_GOOGLE_EXPORTS, ...options.exports }
14
+ const originOf = (origin: string): string => new URL(origin).origin
15
+ const drive = originOf(origins.drive)
16
+ const usercontent = originOf(origins.usercontent)
17
+ const docs = originOf(origins.docs)
18
+ const api = originOf(origins.api)
19
+ const hosts = {
20
+ drive: new URL(drive).host, usercontent: new URL(usercontent).host, docs: new URL(docs).host, accounts: new URL(origins.accounts).host,
21
+ }
22
+
23
+ const read = (url: string): URL | undefined => {
24
+ try {
25
+ const parsed = new URL(url)
26
+ return parsed.protocol === 'https:' || parsed.protocol === 'http:' ? parsed : undefined
27
+ } catch {
28
+ return undefined
29
+ }
30
+ }
31
+
32
+ const parse: GoogleDriveUrlHelper['parse'] = url => {
33
+ const parsed = read(url)
34
+ if (parsed == null) return undefined
35
+ const host = parsed.host.toLowerCase()
36
+ const path = parsed.pathname
37
+ const resourceKey = parsed.searchParams.get('resourcekey') ?? undefined
38
+ const link = (kind: GoogleDriveKind, id: string | null | undefined): GoogleDriveLink | undefined =>
39
+ id != null && DRIVE_ID_PATTERN.test(id) ? { kind, id, ...(resourceKey != null && resourceKey !== '' ? { resourceKey } : {}) } : undefined
40
+
41
+ if (host === hosts.drive) {
42
+ const folder = /^\/drive\/(?:u\/\d+\/|mobile\/)?folders\/([^/]+)/.exec(path)
43
+ if (folder != null) return link(GoogleDriveKind.Folder, folder[1])
44
+ if (/^\/(?:embedded)?folderview\/?$/.test(path)) return link(GoogleDriveKind.Folder, parsed.searchParams.get('id'))
45
+ const file = /^\/file\/(?:u\/\d+\/)?d\/([^/]+)/.exec(path)
46
+ if (file != null) return link(GoogleDriveKind.File, file[1])
47
+ if (/^\/(?:u\/\d+\/)?uc\/?$/.test(path)) return link(GoogleDriveKind.File, parsed.searchParams.get('id'))
48
+ if (/^\/open\/?$/.test(path)) return link(GoogleDriveKind.Unresolved, parsed.searchParams.get('id'))
49
+ return undefined
50
+ }
51
+ if (host === hosts.usercontent) {
52
+ return /^\/(?:download|uc)\/?$/.test(path) ? link(GoogleDriveKind.File, parsed.searchParams.get('id')) : undefined
53
+ }
54
+ if (host === hosts.docs) {
55
+ const editor = /^\/(document|spreadsheets|presentation|drawings)\/(?:u\/\d+\/)?d\/([^/]+)/.exec(path)
56
+ if (editor != null) return link(EDITOR_PATHS[editor[1]!]!, editor[2])
57
+ }
58
+ return undefined
59
+ }
60
+
61
+ const withKey = (url: URL, resourceKey?: string): string => {
62
+ if (resourceKey != null && resourceKey !== '') url.searchParams.set('resourcekey', resourceKey)
63
+ return url.href
64
+ }
65
+
66
+ const downloadUrl: GoogleDriveUrlHelper['downloadUrl'] = (id, resourceKey) => {
67
+ const url = new URL('/download', usercontent)
68
+ url.searchParams.set('id', id)
69
+ url.searchParams.set('export', 'download')
70
+ url.searchParams.set('confirm', 't')
71
+ return withKey(url, resourceKey)
72
+ }
73
+
74
+ const exportOf: GoogleDriveUrlHelper['exportOf'] = (kind, id) => {
75
+ const format = kind === GoogleDriveKind.Document ? formats.document
76
+ : kind === GoogleDriveKind.Spreadsheet ? formats.spreadsheet
77
+ : kind === GoogleDriveKind.Presentation ? formats.presentation
78
+ : formats.drawing
79
+ const path = kind === GoogleDriveKind.Document ? `/document/d/${id}/export?format=${format}`
80
+ : kind === GoogleDriveKind.Spreadsheet ? `/spreadsheets/d/${id}/export?format=${format}`
81
+ : kind === GoogleDriveKind.Presentation ? `/presentation/d/${id}/export/${format}`
82
+ : `/drawings/d/${id}/export/${format}`
83
+ return { url: new URL(path, docs).href, extension: EXPORT_EXTENSIONS[format] ?? format }
84
+ }
85
+
86
+ const folderViewUrl: GoogleDriveUrlHelper['folderViewUrl'] = (id, resourceKey) => {
87
+ const url = new URL('/embeddedfolderview', drive)
88
+ url.searchParams.set('id', id)
89
+ return withKey(url, resourceKey)
90
+ }
91
+
92
+ const apiListUrl: GoogleDriveUrlHelper['apiListUrl'] = (folderId, pageToken) => {
93
+ if (!DRIVE_ID_PATTERN.test(folderId)) throw new SyntaxError(`Not a Drive id: ${folderId}`)
94
+ const url = new URL('/drive/v3/files', api)
95
+ url.searchParams.set('q', `'${folderId}' in parents and trashed=false`)
96
+ url.searchParams.set('fields', `nextPageToken,files(${DRIVE_API_ITEM_FIELDS})`)
97
+ url.searchParams.set('pageSize', String(DRIVE_API_PAGE_SIZE))
98
+ url.searchParams.set('supportsAllDrives', 'true')
99
+ url.searchParams.set('includeItemsFromAllDrives', 'true')
100
+ if (pageToken != null) url.searchParams.set('pageToken', pageToken)
101
+ return url.href
102
+ }
103
+
104
+ const apiFileUrl: GoogleDriveUrlHelper['apiFileUrl'] = id => {
105
+ const url = new URL(`/drive/v3/files/${encodeURIComponent(id)}`, api)
106
+ url.searchParams.set('fields', DRIVE_API_ITEM_FIELDS)
107
+ url.searchParams.set('supportsAllDrives', 'true')
108
+ return url.href
109
+ }
110
+
111
+ const hostOf = (url: string): string | undefined => read(url)?.host.toLowerCase()
112
+
113
+ const isSignIn: GoogleDriveUrlHelper['isSignIn'] = url => hostOf(url) === hosts.accounts
114
+
115
+ const owns: GoogleDriveUrlHelper['owns'] = url => {
116
+ const host = hostOf(url)
117
+ return host != null && (host === hosts.drive || host === hosts.usercontent || host === hosts.docs)
118
+ }
119
+
120
+ return { parse, downloadUrl, exportOf, folderViewUrl, apiListUrl, apiFileUrl, isSignIn, owns }
121
+ }
@@ -0,0 +1,9 @@
1
+ /** File names as Drive gives them, made into path segments. */
2
+ export interface NameUtils {
3
+ /** A Drive title as one storable segment: separators and control characters become `_`, `.`/`..`/empty become `_`. */
4
+ segment: (name: string) => string
5
+ /** The name with `.<extension>` unless it already ends with it (case-insensitive). */
6
+ withExtension: (name: string, extension: string) => string
7
+ /** The file name a `Content-Disposition` carries — `filename*` first — reduced to its last path part. */
8
+ fromDisposition: (header: string | null | undefined) => string | undefined
9
+ }
@@ -0,0 +1,36 @@
1
+ import type { NameUtils } from './names/types.js'
2
+
3
+ export const createNameUtils = (): NameUtils => {
4
+ const segment: NameUtils['segment'] = name => {
5
+ // eslint-disable-next-line no-control-regex
6
+ const clean = name.replace(/[\u0000-\u001f\u007f/\\]/g, '_').trim()
7
+ return clean === '' || clean === '.' || clean === '..' ? '_' : clean
8
+ }
9
+
10
+ const withExtension: NameUtils['withExtension'] = (name, extension) =>
11
+ name.toLowerCase().endsWith(`.${extension.toLowerCase()}`) ? name : `${name}.${extension}`
12
+
13
+ const lastPart = (name: string): string | undefined => {
14
+ const last = name.split(/[/\\]/).pop()?.trim()
15
+ return last == null || last === '' ? undefined : last
16
+ }
17
+
18
+ const fromDisposition: NameUtils['fromDisposition'] = header => {
19
+ if (header == null || header === '') return undefined
20
+ const extended = /filename\*\s*=\s*([^']*)'[^']*'([^;]+)/i.exec(header)
21
+ if (extended != null) {
22
+ try {
23
+ return lastPart(decodeURIComponent(extended[2]!.trim().replace(/^"|"$/g, '')))
24
+ } catch {
25
+ // A malformed escape falls back to the plain filename.
26
+ }
27
+ }
28
+ const plain = /filename\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([^;]+))/i.exec(header)
29
+ const value = plain?.[1]?.replace(/\\(.)/g, '$1') ?? plain?.[2]?.trim()
30
+ return value != null ? lastPart(value) : undefined
31
+ }
32
+
33
+ return { segment, withExtension, fromDisposition }
34
+ }
35
+
36
+ export const nameUtils = createNameUtils()