One storage API for Google Drive, Nextcloud, and S3-compatible clouds, in TypeScript and Python.
TypeScript byoccloud-storagecloudflare-r2encryptiongoogle-drivenextcloudoauth2pkcepythons3sdkstoragetypescriptwebdav
{
"$comment": "BYOC operation-surface contract. Unlike the other fixtures, this one pins NO wire bytes -- it pins which operations exist. Both SDKs write identical bytes whether or not an adapter implements copy(), so no byte-level vector can catch an adapter that is simply missing a method. That is exactly how the TypeScript SDK came to implement copy() on all three network adapters while the Python S3 and Google Drive adapters had none, and how both clients ended up with no copy() at all, leaving three working implementations unreachable. Operation names below are given in snake_case as the neutral form; each SDK maps them to its own convention (TypeScript camelCases them). Method NAMING is deliberately not part of the contract -- only which operations exist.",
"version": 1,
"client_operations": {
"$comment": "Operations the universal client must expose in every SDK. An operation implemented on an adapter but absent from the client is unreachable by callers and does not count as shipped.",
"required": [
"connect",
"disconnect",
"upload",
"download",
"delete",
"list",
"exists",
"metadata",
"read_text",
"read_bytes",
"write_text",
"write_bytes",
"create_folder",
"move",
"copy",
"get_quota",
"signed_url",
"create_upload_grant",
"walk",
"delete_tree",
"delete_many",
"capabilities",
"has_capability",
"manifest",
"use_provider",
"get_providers",
"migrate",
"backup"
]
},
"provider_operations": {
"$comment": "Every adapter must implement the required set. Optional operations are only required when the matching capability is declared true -- see capability_contracts.",
"required": [
"connect",
"disconnect",
"upload",
"download",
"delete",
"list",
"exists",
"metadata",
"manifest",
"capabilities"
],
"optional": ["create_folder", "move", "copy", "quota", "signed_url", "create_upload_grant"]
},
"capability_contracts": {
"$comment": "A declared capability is a promise to the caller, who feature-detects on it instead of catching an exception. Declaring a capability without the backing method is a lie that surfaces as an AttributeError or undefined-is-not-a-function at the call site. Python's S3 and Google Drive adapters both declared server_side_copy=true with no copy() method until 0.3.0.",
"contracts": [
{
"capability": "folders",
"requires_operation": "create_folder",
"$comment": "A provider without real folders must report false and let create_folder raise CAPABILITY_UNSUPPORTED, rather than faking folders with key prefixes."
},
{
"capability": "server_side_copy",
"requires_operation": "copy"
},
{
"capability": "quota",
"requires_operation": "quota"
},
{
"capability": "direct_upload",
"requires_operation": "create_upload_grant",
"$comment": "Declaring direct_upload promises a browser can be handed a URL and upload to it without the application's credentials. See upload-grant.json for the wire format."
},
{
"capability": "public_urls",
"requires_operation": "signed_url",
"$comment": "Only S3-compatible backends can hand a browser a URL that works without the caller's credentials. Drive and WebDAV report false rather than returning a link that would 401."
}
]
},
"providers": {
"$comment": "The operation surface each shipped adapter is expected to have, in both SDKs. Adding an adapter means adding it here.",
"google-drive": {
"operations": ["create_folder", "move", "copy", "quota", "create_upload_grant"],
"capabilities": { "folders": true, "quota": true, "server_side_copy": true, "public_urls": false, "direct_upload": true }
},
"s3-compatible": {
"operations": ["move", "copy", "signed_url", "create_upload_grant"],
"capabilities": {
"folders": false,
"quota": false,
"server_side_copy": true,
"public_urls": true,
"direct_upload": true
},
"$comment": "S3 has no native folders and reports no account quota. Both stay false rather than being faked."
},
"webdav": {
"operations": ["create_folder", "move", "copy", "quota"],
"capabilities": { "folders": true, "quota": true, "server_side_copy": true, "public_urls": false, "direct_upload": false }
},
"local": {
"operations": ["create_folder", "move", "copy", "quota"],
"capabilities": { "folders": true, "quota": true, "server_side_copy": true, "public_urls": false, "direct_upload": false },
"$comment": "Quota reports the backing filesystem's usage, not the root directory's."
},
"memory": {
"operations": ["move", "copy", "quota"],
"capabilities": { "folders": false, "quota": true, "server_side_copy": true, "public_urls": false, "direct_upload": false },
"$comment": "Models a flat key-value object store, the shape S3 and R2 have, so it has no real folders either."
}
}
}