@owlmeans/llm-reader-google-drive 0.0.0-stage → 0.2.1-alpha.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/README.md +113 -2
- package/agent-meta/manifest.json +16 -0
- package/agent-meta/skills/llm-reader-google-drive/SKILL.md +131 -0
- package/build/consts.d.ts +45 -0
- package/build/consts.d.ts.map +1 -0
- package/build/consts.js +54 -0
- package/build/consts.js.map +1 -0
- package/build/consts.local.d.ts +3 -0
- package/build/consts.local.d.ts.map +1 -0
- package/build/consts.local.js +3 -0
- package/build/consts.local.js.map +1 -0
- package/build/errors.d.ts +14 -0
- package/build/errors.d.ts.map +1 -0
- package/build/errors.js +26 -0
- package/build/errors.js.map +1 -0
- package/build/index.d.ts +6 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +5 -0
- package/build/index.js.map +1 -0
- package/build/source/api.d.ts +9 -0
- package/build/source/api.d.ts.map +1 -0
- package/build/source/api.js +80 -0
- package/build/source/api.js.map +1 -0
- package/build/source/consts.local.d.ts +33 -0
- package/build/source/consts.local.d.ts.map +1 -0
- package/build/source/consts.local.js +39 -0
- package/build/source/consts.local.js.map +1 -0
- package/build/source/embedded.d.ts +10 -0
- package/build/source/embedded.d.ts.map +1 -0
- package/build/source/embedded.js +82 -0
- package/build/source/embedded.js.map +1 -0
- package/build/source/http.d.ts +6 -0
- package/build/source/http.d.ts.map +1 -0
- package/build/source/http.js +61 -0
- package/build/source/http.js.map +1 -0
- package/build/source/probe.d.ts +10 -0
- package/build/source/probe.d.ts.map +1 -0
- package/build/source/probe.js +80 -0
- package/build/source/probe.js.map +1 -0
- package/build/source/types.local.d.ts +87 -0
- package/build/source/types.local.d.ts.map +1 -0
- package/build/source/types.local.js +2 -0
- package/build/source/types.local.js.map +1 -0
- package/build/source.d.ts +22 -0
- package/build/source.d.ts.map +1 -0
- package/build/source.js +169 -0
- package/build/source.js.map +1 -0
- package/build/types.d.ts +79 -0
- package/build/types.d.ts.map +1 -0
- package/build/types.js +2 -0
- package/build/types.js.map +1 -0
- package/build/url/consts.local.d.ts +10 -0
- package/build/url/consts.local.d.ts.map +1 -0
- package/build/url/consts.local.js +15 -0
- package/build/url/consts.local.js.map +1 -0
- package/build/url.d.ts +8 -0
- package/build/url.d.ts.map +1 -0
- package/build/url.js +117 -0
- package/build/url.js.map +1 -0
- package/build/utils/names/types.d.ts +10 -0
- package/build/utils/names/types.d.ts.map +1 -0
- package/build/utils/names/types.js +2 -0
- package/build/utils/names/types.js.map +1 -0
- package/build/utils/names.d.ts +4 -0
- package/build/utils/names.d.ts.map +1 -0
- package/build/utils/names.js +31 -0
- package/build/utils/names.js.map +1 -0
- package/package.json +62 -4
- package/src/consts.local.ts +2 -0
- package/src/consts.ts +60 -0
- package/src/errors.ts +30 -0
- package/src/index.ts +7 -0
- package/src/source/api.ts +81 -0
- package/src/source/consts.local.ts +52 -0
- package/src/source/embedded.ts +83 -0
- package/src/source/http.ts +66 -0
- package/src/source/probe.ts +84 -0
- package/src/source/types.local.ts +91 -0
- package/src/source.ts +179 -0
- package/src/types.ts +86 -0
- package/src/url/consts.local.ts +19 -0
- package/src/url.ts +121 -0
- package/src/utils/names/types.ts +9 -0
- package/src/utils/names.ts +36 -0
- package/tests/context.ts +212 -0
- package/tests/fixtures.ts +88 -0
- package/tests/live.spec.ts +53 -0
- package/tests/source.spec.ts +189 -0
- package/tests/tsconfig.json +12 -0
- 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()
|