@wtfalch/files 0.7.0 → 0.9.0

package/README.md

@@ -38,8 +38,8 @@ a day. `uploadPartUrls(uploadId, from, count)` returns presigned URLs for up to
 100 parts. PUT part n as bytes `[(n-1)*partBytes, n*partBytes)` and keep each
 response's `ETag` header. Then call `confirmUpload(uploadId, parts)` with every
 part in order. To resume, ask for fresh URLs for the parts that failed. A
-multipart file has `checksum: null`. The R2 backend supports this; the
-local-disk backend does not yet.
+multipart file has `checksum: null`. Both the R2 and local-disk backends
+support this.
 
 `getFile(id, version)` and `downloadFile(id, { version })` pin the read to an
 exact file version. A mismatch against the file's current version throws
@@ -51,12 +51,44 @@ older version to fall back to. Every `StoredFile` also carries `sha256`
 version (`null` if that upload is no longer on record, or the file was never
 confirmed).
 
+`downloadFile`'s URL accepts an HTTP `Range` request header for partial
+reads (`bytes=start-end`, `start-`, or `-suffix`); a satisfiable range answers
+`206` with `Content-Range`, and one past the end of the file answers `416`.
+Both the R2 and local-disk backends support it.
+
 Files can sit in folders inside a collection. Pass `path` (for example
 `reports/2026`) when you reserve an upload. `listFiles(collectionId, { path })`
 lists the files directly in that folder, and `listFolders(collectionId, path)`
 lists its subfolders. A folder exists while it holds a file, so there are no
-empty folders. A replacement keeps the file's path; moving a file is not
-supported yet.
+empty folders. A replacement keeps the file's path; `moveFile(id, { path, name,
+version })` changes either or both within the same collection, without
+re-uploading -- moving across collections is not supported. `version` is the
+file's current version (optimistic concurrency, same as a version-pinned
+read): a stale value throws `ApiError` with `status: 409`. A move does not
+change `version`, so two moves at the same version both apply and the last one
+wins. Like an upload, a move may share a path and name with another file.
+
+`listFiles(collectionId, { name })` finds a file by name: a case-insensitive
+substring match, composing with `path`, `after` and `limit`. It only ever
+matches files the caller can already list -- it narrows an existing read, it
+never widens one.
+
+`deleteFiles(fileIds)` deletes a folder or several files at once: up to 100
+ids, in one transaction, all within the caller's own organisation -- either
+every file is deleted or none is. A duplicate id in the list is collapsed to
+a single delete. An id that does not exist, or that the caller cannot
+delete, refuses the whole batch with the same error a single `deleteFile`
+call for that id would give.
+
+`copyFile(fileId, { collectionId, path, name })` copies an existing file's
+bytes to a brand new file, in the same collection (the default) or another
+one in your own organisation, with an optional new path and/or name -- every
+field is optional, and an empty `{}` duplicates the file in place. It counts
+against quota and the upload price exactly like a fresh upload of the same
+bytes, and throws `ApiError` with `status: 409` if the source changes
+mid-copy. Copying a file in another organisation is impossible: it 404s the
+same way any other cross-organisation file read does. Variants and share
+links are never copied.
 
 Image files can be resized on demand instead of a tenant running its own
 thumbnail pipeline: `getFileVariant(fileId, width, format)` returns a signed
@@ -67,6 +99,144 @@ file whose content type `sharp` can decode (JPEG, PNG, WebP, GIF, AVIF)
 qualifies -- anything else answers `invalid_request`. A variant's bytes count
 against the same byte quota an upload does.
 
+## Audience
+
+Every file has an **audience** (issue #71): the list of references, besides
+its owner, who may see it. `reserveUpload`'s `audience` is a plain
+`string[]` of references:
+
+| Reference | Who it admits |
+|---|---|
+| `"org"` | Everyone in the organisation who has files read. |
+| `"person:<subject>"` | One signed-in person. |
+| `"team:<teamId>"` | Members of that authz team whose own `files.files:read` grant covers it. |
+| `"group:<app>:<type>/<id>"`, e.g. `"group:chat:room/!abc"` | Members of a group the named app keeps in sync with files. |
+
+Omitted, `audience` defaults to `[]` -- **the uploader only**, whether the
+uploader is a signed-in person or an app key. It only applies to a brand new
+file; a `replace` upload keeps the target file's existing audience and
+throws `ApiError` with `status: 400` if `audience` is also given.
+`getFile`/`listFiles` and the rest carry the file's current setting as
+`StoredFile.audience`. The owner changes it afterward with
+`setFileAudience(fileId, { audience, shareable? })`; a holder of
+`files.files:read-any` (below) may also change it -- a caller who only sees
+the file BECAUSE of the audience (a listed person, or a team or group
+member) may not.
+
+A `team:`/`group:` reference gives its members **read only**: it narrows
+get/download/a variant/list/folders/the source of a copy/listing shares, but
+never delete, move, replace or share -- a write still needs its own
+permission over the file's real collection, unaffected by the audience.
+
+Three shapes this covers:
+- **A DM or private note**: no audience at all (owner only) -- exactly the
+  default.
+- **A room's shared files**: `["group:chat:room/!abc"]`, kept in sync by the
+  room's own app through a group-membership API (a later addition to this
+  SDK); every current member reads the room's files without files granting
+  them anything itself.
+- **A personal-files area a support team can see**: `["team:<teamId>"]` --
+  the person's own files, readable by anyone on that team whose grant covers
+  it, still only ever deletable/replaceable by the owner or a
+  `files.files:replace` grant scoped directly to the file (never merely by
+  being on the team).
+
+### Groups
+
+A group is owned by the app that created it (`group:<app>:...`), not by
+Files: Files only checks membership, so a read never waits on the owning
+app. Chat, say, creates `group:chat:room/!abc` and keeps its membership in
+sync as its own room changes; any file whose `audience` names that ref
+admits every current member to a read, nothing more.
+
+Every write needs `files.groups:update` (granted to no built-in role by
+default -- groups are app-owned, so only the owning app's own key holds
+it), and is refused unless that key's own `--app` (set once, at
+`keys:issue --app <slug>`, apps/host's README) names the SAME app the
+group ref itself names -- chat's key can write `group:chat:...`, never
+`group:lokessmie:...`. A human is always refused. This ownership rule is
+provisional and may change. Reads need `files.groups:read` and carry no
+such restriction.
+
+```ts
+const group = await client.createGroup('group:chat:room/!abc'); // idempotent
+await client.setGroupMembers('group:chat:room/!abc', [
+  { class: 'human', id: personId },
+]); // replaces the full list atomically, never a merge
+await client.addGroupMember('group:chat:room/!abc', { class: 'human', id: otherPersonId }); // idempotent
+await client.removeGroupMember('group:chat:room/!abc', { class: 'human', id: personId }); // idempotent
+const members = await client.listGroupMembers('group:chat:room/!abc');
+await client.deleteGroup('group:chat:room/!abc'); // idempotent, cascades to its members
+```
+
+Deleting a group never touches any file's `audience`: a file that named it
+simply stops matching, the same way removing a member does.
+
+### Shareable links
+
+Each file also carries `shareable: boolean`. `createShare` refuses a file
+whose `shareable` is `false`; a share link stops resolving the moment its
+file's `shareable` turns `false`, or its creator drops out of the audience,
+whichever comes first -- both checked fresh on every redemption. Omitted at
+upload time, `shareable` defaults to `false` for a signed-in person (a link
+is an extra, deliberate step) and `true` for any other principal class (an
+app key), so lokessmie's and offline.tf's existing app-key integrations keep
+minting links unchanged. Change it afterward with `setFileAudience`'s own
+`shareable` field.
+
+### Seeing everything: `files.files:read-any`
+
+A sensitive permission: read any file in the organisation, whatever its
+audience. Every get/download/variant/list/folders/copy-source/share-listing
+call still needs its own base permission too UNLESS the caller holds
+read_any, in which case that alone suffices -- an auditor or devops role
+granted only read_any needs no separate `files.files:read`/
+`files.files:download`/`files.shares:read` grant to use it. Granted by
+default to the built-in admin role (revocable per organisation, or
+grantable to another role) and, unconditionally, to every app key -- the
+same continuity `shareable`'s own app-key default protects. Every read
+admitted ONLY by read_any writes its own audit row (a distinct action per
+underlying permission, e.g. `files.file_read_privileged`), and a write
+(move, replace, delete, share, an audience change) that read_any alone
+admitted writes one too, alongside its ordinary action.
+
+Whatever the caller's role, an audience or read_any check that fails throws
+the same `ApiError` a caller lacking the underlying permission outright
+would get -- a file hidden this way is never distinguishable from one the
+caller was never granted access to at all.
+
+### My files, Shared with me, and search (issue #72)
+
+Two cross-collection, cursor-paginated lists for a signed-in caller's own
+"files" view, e.g. Agora's:
+
+- `listMyFiles({ after, limit, name })`: every file the caller owns, across
+  every collection in the organisation, newest first.
+- `listSharedFiles({ after, limit, name })`: every file the caller did NOT
+  upload but may read through its audience -- `'org'`, a `'person:'`
+  reference naming them, a `'team:'` reference their own read grant covers,
+  or a `'group:'` reference they belong to. Each result is a `StoredFile`
+  plus its `owner`.
+
+Both return `{ files, next }`; pass a page's `next` back as `after` to fetch
+the next one, `next: null` meaning the last page. `name`, like `listFiles`'s
+own, is a case-insensitive substring match, with the caller's own
+`%`/`_`/`\` matched literally rather than as ILIKE wildcards. There is no
+separate "search everywhere" endpoint: since a file is always either the
+caller's own or someone else's, searching both lists with the same `name`
+and merging the results covers it -- Agora's two lists already need the
+filter for their own search boxes, so a third endpoint would only
+duplicate what calling both already gives.
+
+`listSharedFiles` never includes a file only `files.files:read-any` would
+admit -- unlike `listFiles`/`getFile`, which do, and audit it. Read-any is
+an audit-grade capability to read any file in the organisation; folding it
+into "Shared with me" would turn an ordinary person's own list into a full
+organisation directory the moment they held it, with no separate audit
+trail the way every other read-any bypass gets. A caller that wants
+everything, read-any included, is `listFiles`/`listFolders` themselves
+(per collection), unchanged by this feature.
+
 The root export provides the client and public request/response types.
 `@wtfalch/files/client` is also supported. There are no server, database,
 migration, provider-adapter or authorization-engine exports. The service
@@ -75,6 +245,43 @@ implementation is maintained in a private repository.
 The first 0.1.0 SDK targets the new service API. Production migration from Valet
 is a separate rollout; installing the SDK does not migrate accounts or files.
 
+## Calling from a browser through a same-origin proxy
+
+The files host itself has no CORS headers and no public domain (task #70):
+`credential()` above must never be a privileged service credential in
+browser code, and a browser cannot reach the host directly either way. A
+browser app such as Agora instead runs its own same-origin proxy -- a route
+on the app's own origin that forwards `Authorization` and
+`X-Organisation-Id` to the files host on its private network, stripping any
+cookies -- and points the SDK at itself:
+
+```ts
+const files = createFilesClient({
+  url: window.location.origin,
+  // The person's own @wtfalch/auth access token, read fresh on every call
+  // rather than captured once -- the same shape Agora already passes to
+  // its calendar client's `getAccessToken`.
+  credential: () => accessTokenRef.current,
+  organisationId, // the person's files organisation
+  // Only needed if the proxy is mounted under a path prefix, e.g. `/_files`
+  // -- the SDK always builds request paths from the origin's root
+  // (`/v1/...`), so a prefixed proxy needs its path put back before the
+  // real request leaves the browser.
+  fetch: (input, init) => {
+    const target = new URL(input instanceof Request ? input.url : input);
+    target.pathname = `/_files${target.pathname}`;
+    return fetch(target, init);
+  },
+});
+```
+
+The files host verifies that access token itself -- see `@wtfalch/files-host`'s
+README, "Person tokens (Agora and other browser callers)" -- and acts as
+that person in `organisationId`, subject to their real membership there. A
+credential this SDK cannot turn into a bearer at all has no separate
+transport option here: `credential()` already sends whatever it returns as
+`Authorization: Bearer`, machine key or person token alike.
+
 ## Migrating from `@wtfalch/storage`
 
 `@wtfalch/storage` is this same SDK under its pre-rename name (the 2026-09-20
@@ -137,6 +344,10 @@ for, so a reader falls back to the id.
 host; use `updateOrganisationCeiling()` to change them. Byte and money totals
 remain decimal strings, including values above JavaScript's safe integer range.
 
+Pass `name` and `owner` (a subject id) to onboard Agora for a new organisation.
+The 201 result then carries `agoraKey: { id, secret }` once. Store the secret at
+once: a repeat call returns 200 without it.
+
 For the operator application's existing transport, compose the SDK on the server:
 
 ```ts
@@ -154,3 +365,97 @@ if (!result.created) {
 `allowInsecureHttp` should come from trusted deployment configuration, never a
 request parameter. Keep application permission checks inside the supplied fetch
 and retain the UI's error mapping when replacing a custom client with the SDK.
+
+### Deleting an organisation
+
+`deleteOrganisation(organisationId)` deletes an organisation with a 7-day
+grace period: it suspends the organisation immediately (every tenant write
+and public share link is refused straight away, the same as a ceiling-update
+suspension) and marks it deleted. `restoreOrganisation(organisationId)` undoes
+that within the 7 days, clearing the suspension the delete itself set back to
+whatever the organisation's suspension was before -- an operator suspension
+set on purpose earlier is never silently cleared by a restore. Both need
+`files.organisations:delete`, a permission of its own that
+`files.organisations:provision` does not include.
+
+```ts
+const deleted = await management.deleteOrganisation(organisationId);
+// deleted.deletedAt is the ISO timestamp the grace period counts from.
+await management.restoreOrganisation(organisationId); // any time in the next 7 days
+```
+
+Deleting is idempotent: deleting an organisation that is already deleted
+succeeds again, unchanged, rather than throwing, so a caller that never saw a
+first call's response (a dropped connection, a timeout) can always retry.
+Deleting one that was never provisioned throws `ApiError` with `status: 404`.
+Once the grace period passes, a daily job purges the organisation for good --
+every row and every stored object -- and `restoreOrganisation` then throws
+`ApiError` with `status: 404` too, the same as for an organisation that was
+never deleted; the two are not distinguishable from the client, by design.
+
+### Membership
+
+The product that owns its users (Agora, lokessmie) writes memberships in its
+own files organisation -- files never auto-admits a signed-in person by token
+alone. `subject` is always the person's token subject (a `human` principal);
+`role` is a role key, either the built-in `files_member` role (reads, uploads,
+downloads and shares their own files -- the role a product assigns to an
+ordinary person) or a custom role the organisation defined. Every call needs
+`files.members:read` (list) or `files.members:update` (add/change role/remove),
+held by the calling key for its own organisation only -- `files.members:update`
+is sensitive: a key can never grant or take away a role wider than its own
+authority already covers, so a files-scoped product key can grant
+`files_member` but not, say, `admin` (which also needs billing/tenant
+permissions no files-only key holds).
+
+```ts
+const { members } = await management.listMembers();
+const added = await management.addMember({ subject: personId, role: 'files_member' });
+await management.setMemberRole(personId, 'c_read_only'); // a custom role the org defined
+await management.removeMember(personId);
+```
+
+`addMember` is idempotent: naming a subject who is already a member returns
+their current row unchanged (`role` in the input is ignored in that case) --
+use `setMemberRole` to change an existing member's role. `removeMember` is
+idempotent too: removing a subject who is not, or no longer, a member still
+succeeds. Both, like `setMemberRole`, throw `ApiError` with `status: 422` if
+the calling key cannot delegate the role involved.
+
+## Webhooks
+
+`management.setWebhook(url)` sets the single outbound endpoint for the
+caller's organisation; `management.setWebhook(null)` clears it and stops
+delivery. `url` must be `https://`, under 2048 characters, with no embedded
+credentials, and not point at an obviously local or private address (this is
+a syntactic check only, not DNS-resolution-time SSRF hardening). A successful
+set returns a fresh `secret`, generated on every call -- this is also how you
+rotate it. `secret` is returned only from `setWebhook()`; `management.getWebhook()`
+returns just the current `url`. Both calls require the same permission as the
+tenant's quota and budget calls.
+
+Four event types are delivered, each as a JSON POST body of the shape
+`{ type, occurredAt, organisationId, data }`:
+
+- `files.upload_confirmed`, sent after an upload confirms, with `data`:
+  `fileId`, `collectionId`, `bytes`, `contentType`, `checksum`, `sha256` and
+  `principalRef` (the confirming principal).
+- `files.quota_near_ceiling`, sent when a fresh read of the organisation's
+  committed bytes (used plus reserved) reaches 90% of its effective cap, with
+  `data`: `usedBytes`, `reservedBytes` and `ceilingBytes`.
+- `files.file_deleted`, sent after `deleteFile()` commits, with `data`:
+  `fileId`, `collectionId` and `version` (the version at deletion).
+- `files.variant_created`, sent when `getFileVariant()` generates and stores a
+  new resized copy (not on a cache hit), with `data`: `fileId`, `version`,
+  `width`, `format` and `bytes`.
+
+Every request carries an `x-files-webhook-signature: sha256=<hex>` header,
+the HMAC-SHA256 of the exact raw request body using the `secret` from
+`setWebhook()`. Verify it by recomputing that HMAC over the raw body you
+received and comparing it to the header before trusting the payload.
+
+Delivery is best effort: it never retries, times out after 5 seconds, and a
+failed or unreachable endpoint never fails the upload or quota check that
+triggered it. There is no persistent retry queue, so a receiver must treat
+delivery as at-most-once (or not-at-all) and reconcile through the regular
+API when a delivery is missed.

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type ClientOptions, type ManagementClientOptions } from './transport.js';
-import type { AuditPage, AuditQuery, BudgetSummary, CreatedShare, FilesRate, OrganisationShare, OrganisationSummary, ProvisionOrganisationInput, ProvisionOrganisationResult, QuotaSummary, SetRateInput, SetWebhookResult, Share, StoredFile, UpdateOrganisationCeilingInput, UploadInput, UploadReservation, UploadedPart, UsageDay, VariantFormat, VariantWidth, WebhookConfig } from './types.js';
+import type { AddMemberInput, AuditPage, AuditQuery, BudgetSummary, CopyFileInput, CreatedShare, FilesPage, FilesRate, Group, GroupMember, Member, MoveFileInput, OrganisationShare, OrganisationSummary, ProvisionOrganisationInput, ProvisionOrganisationResult, QuotaSummary, SetFileAudienceInput, SetRateInput, SetWebhookResult, Share, SharedFilesPage, StoredFile, UpdateOrganisationCeilingInput, UploadInput, UploadReservation, UploadedPart, UsageDay, VariantFormat, VariantWidth, WebhookConfig } from './types.js';
 export { ApiError, type ClientOptions, type ManagementClientOptions } from './transport.js';
 export declare function createFilesClient(options: ClientOptions): {
     createCollection: (name: string) => Promise<{
@@ -37,18 +37,77 @@ export declare function createFilesClient(options: ClientOptions): {
         expiresIn: number;
     }>;
     deleteFile: (id: string) => Promise<void>;
-    /** `path` lists only the files directly in that folder. */
+    /** Copies an existing file's bytes to a brand new file (task F), in the
+     * same collection (the default) or another one in your own
+     * organisation, with an optional new path and/or name. Counts against
+     * quota and the upload price exactly like a fresh upload of the same
+     * bytes; throws `ApiError` with `status: 409` if the source changes
+     * mid-copy. Variants and share links are never copied. */
+    copyFile: (id: string, input?: CopyFileInput) => Promise<StoredFile>;
+    /** Deletes up to 100 files, in the caller's own organisation, in one
+     * transaction: either every file goes or none does. A duplicate id
+     * collapses to a single delete. An id that does not exist or is not
+     * permitted refuses the whole batch with the same error a single
+     * `deleteFile` of that id would give. */
+    deleteFiles: (fileIds: string[]) => Promise<void>;
+    /** Change `path` and/or `name` within the same collection, without
+     * re-uploading (task D). `version` is optimistic concurrency: a stale
+     * value, or a target `path`+`name` another file already occupies, both
+     * throw `ApiError` with `status: 409`. */
+    moveFile: (id: string, input: MoveFileInput) => Promise<StoredFile>;
+    /** Change a file's audience and/or its `shareable` flag (issue #71).
+     * Only the file's owner, or a holder of `files.files:read-any`, may
+     * call this -- listed people, team or group members may not, even with
+     * a broader `files.files:replace` grant. */
+    setFileAudience: (id: string, input: SetFileAudienceInput) => Promise<StoredFile>;
+    /** `path` lists only the files directly in that folder. `name` is a
+     * case-insensitive substring match against the file name. */
     listFiles: (collection: string, page?: {
         after?: string;
         limit?: number;
         path?: string;
+        name?: string;
     }) => Promise<StoredFile[]>;
     /** The immediate subfolders of `path` ('' is the root) that hold at least
      * one file the caller can read. */
     listFolders: (collection: string, path?: string) => Promise<string[]>;
+    /** Agora's "My files" (issue #72): every file the caller owns, across
+     * every collection in the organisation, newest first. `name`, like
+     * `listFiles`'s own, is a case-insensitive substring match. Pass a
+     * page's `next` back as `after` to fetch the next one; `next: null`
+     * means this was the last page. */
+    listMyFiles: (page?: {
+        after?: string;
+        limit?: number;
+        name?: string;
+    }) => Promise<FilesPage>;
+    /** Agora's "Shared with me" (issue #72): every file the caller did NOT
+     * upload but may read through its `audience` -- 'org', a 'person:'
+     * reference naming them, a 'team:' reference their own read grant
+     * covers, or a 'group:' reference they belong to -- newest first, each
+     * with its `owner`. Never includes a file only `files.files:read-any`
+     * would admit: this is what the caller ordinarily reads, not an audit
+     * view of the whole organisation. */
+    listSharedFiles: (page?: {
+        after?: string;
+        limit?: number;
+        name?: string;
+    }) => Promise<SharedFilesPage>;
     createShare: (fileId: string, expiresAt: string | null) => Promise<CreatedShare>;
     listShares: (fileId: string) => Promise<Share[]>;
     revokeShare: (shareId: string) => Promise<void>;
+    /** Idempotent: a group ref that already exists is returned unchanged. */
+    createGroup: (groupRef: string) => Promise<Group>;
+    getGroup: (groupRef: string) => Promise<Group>;
+    /** Idempotent: a group ref that does not exist is a no-op. */
+    deleteGroup: (groupRef: string) => Promise<void>;
+    listGroupMembers: (groupRef: string) => Promise<GroupMember[]>;
+    /** Replaces the group's full member list atomically -- never a merge. */
+    setGroupMembers: (groupRef: string, members: GroupMember[]) => Promise<GroupMember[]>;
+    /** Idempotent: a member already present is a no-op. */
+    addGroupMember: (groupRef: string, member: GroupMember) => Promise<void>;
+    /** Idempotent: a member not present is a no-op. */
+    removeGroupMember: (groupRef: string, member: GroupMember) => Promise<void>;
 };
 /** Operator and tenant management routes. `options.fetch` authenticates
  * each request with a signed human proof or an issued management key;
@@ -64,6 +123,8 @@ export declare function createFilesManagementClient(options: ManagementClientOpt
     }>;
     provisionOrganisation: (input: ProvisionOrganisationInput) => Promise<ProvisionOrganisationResult>;
     updateOrganisationCeiling: (organisationId: string, input: UpdateOrganisationCeilingInput) => Promise<OrganisationSummary>;
+    deleteOrganisation: (organisationId: string) => Promise<OrganisationSummary>;
+    restoreOrganisation: (organisationId: string) => Promise<OrganisationSummary>;
     getQuota: () => Promise<QuotaSummary>;
     setQuota: (limitBytes: string | null) => Promise<QuotaSummary>;
     setKeyQuota: (keyId: string, limitBytes: string | null) => Promise<QuotaSummary>;
@@ -78,4 +139,13 @@ export declare function createFilesManagementClient(options: ManagementClientOpt
     }>;
     getWebhook: () => Promise<WebhookConfig>;
     setWebhook: (url: string | null) => Promise<SetWebhookResult>;
+    listMembers: () => Promise<{
+        members: Member[];
+    }>;
+    addMember: (input: AddMemberInput) => Promise<Member>;
+    setMemberRole: (subject: string, role: string) => Promise<Member>;
+    removeMember: (subject: string) => Promise<{
+        subject: string;
+        removed: boolean;
+    }>;
 };

package/dist/client.js

@@ -34,21 +34,86 @@ export function createFilesClient(options) {
         // one of `VARIANT_WIDTHS`; the service answers 400 otherwise.
         getFileVariant: (id, width, format) => call('GET', `/v1/files/${encodeURIComponent(id)}/variants/${width}.${format}`),
         deleteFile: (id) => call('DELETE', `/v1/files/${encodeURIComponent(id)}`),
-        /** `path` lists only the files directly in that folder. */
+        /** Copies an existing file's bytes to a brand new file (task F), in the
+         * same collection (the default) or another one in your own
+         * organisation, with an optional new path and/or name. Counts against
+         * quota and the upload price exactly like a fresh upload of the same
+         * bytes; throws `ApiError` with `status: 409` if the source changes
+         * mid-copy. Variants and share links are never copied. */
+        copyFile: (id, input = {}) => call('POST', `/v1/files/${encodeURIComponent(id)}/copy`, input),
+        /** Deletes up to 100 files, in the caller's own organisation, in one
+         * transaction: either every file goes or none does. A duplicate id
+         * collapses to a single delete. An id that does not exist or is not
+         * permitted refuses the whole batch with the same error a single
+         * `deleteFile` of that id would give. */
+        deleteFiles: (fileIds) => call('DELETE', '/v1/files', { fileIds }),
+        /** Change `path` and/or `name` within the same collection, without
+         * re-uploading (task D). `version` is optimistic concurrency: a stale
+         * value, or a target `path`+`name` another file already occupies, both
+         * throw `ApiError` with `status: 409`. */
+        moveFile: (id, input) => call('PATCH', `/v1/files/${encodeURIComponent(id)}`, input),
+        /** Change a file's audience and/or its `shareable` flag (issue #71).
+         * Only the file's owner, or a holder of `files.files:read-any`, may
+         * call this -- listed people, team or group members may not, even with
+         * a broader `files.files:replace` grant. */
+        setFileAudience: (id, input) => call('PATCH', `/v1/files/${encodeURIComponent(id)}/audience`, input),
+        /** `path` lists only the files directly in that folder. `name` is a
+         * case-insensitive substring match against the file name. */
         listFiles: (collection, page = {}) => call('GET', `/v1/collections/${encodeURIComponent(collection)}/files?${new URLSearchParams({
             ...(page.after ? { after: page.after } : {}),
             ...(page.limit !== undefined ? { limit: String(page.limit) } : {}),
             ...(page.path !== undefined ? { path: page.path } : {}),
+            ...(page.name !== undefined ? { name: page.name } : {}),
         })}`),
         /** The immediate subfolders of `path` ('' is the root) that hold at least
          * one file the caller can read. */
         listFolders: (collection, path = '') => call('GET', `/v1/collections/${encodeURIComponent(collection)}/folders?${new URLSearchParams({ path })}`).then((result) => result.folders),
+        /** Agora's "My files" (issue #72): every file the caller owns, across
+         * every collection in the organisation, newest first. `name`, like
+         * `listFiles`'s own, is a case-insensitive substring match. Pass a
+         * page's `next` back as `after` to fetch the next one; `next: null`
+         * means this was the last page. */
+        listMyFiles: (page = {}) => call('GET', `/v1/files/mine?${new URLSearchParams({
+            ...(page.after ? { after: page.after } : {}),
+            ...(page.limit !== undefined ? { limit: String(page.limit) } : {}),
+            ...(page.name !== undefined ? { name: page.name } : {}),
+        })}`),
+        /** Agora's "Shared with me" (issue #72): every file the caller did NOT
+         * upload but may read through its `audience` -- 'org', a 'person:'
+         * reference naming them, a 'team:' reference their own read grant
+         * covers, or a 'group:' reference they belong to -- newest first, each
+         * with its `owner`. Never includes a file only `files.files:read-any`
+         * would admit: this is what the caller ordinarily reads, not an audit
+         * view of the whole organisation. */
+        listSharedFiles: (page = {}) => call('GET', `/v1/files/shared?${new URLSearchParams({
+            ...(page.after ? { after: page.after } : {}),
+            ...(page.limit !== undefined ? { limit: String(page.limit) } : {}),
+            ...(page.name !== undefined ? { name: page.name } : {}),
+        })}`),
         // Public share links (task S6): `files.files:share`/`files.shares:read`,
         // bearer key or signed request -- both reach the same /v1/files/*
         // routes this client already calls.
         createShare: (fileId, expiresAt) => call('POST', `/v1/files/${encodeURIComponent(fileId)}/shares`, { expiresAt }),
         listShares: (fileId) => call('GET', `/v1/files/${encodeURIComponent(fileId)}/shares`).then((r) => r.shares),
         revokeShare: (shareId) => call('DELETE', `/v1/shares/${encodeURIComponent(shareId)}`),
+        // App-owned groups (task G, campaign 2026-09-25-agora-files):
+        // `files.groups:read`/`files.groups:update`, granted only to the app
+        // keys that need them (groups are app-owned, no built-in role holds
+        // either). A write is refused (403) unless the calling key's own
+        // `--app` (apps/host README) names the group ref's own <app> segment;
+        // a human is always refused. This ownership rule is provisional.
+        /** Idempotent: a group ref that already exists is returned unchanged. */
+        createGroup: (groupRef) => call('POST', '/v1/groups', { groupRef }),
+        getGroup: (groupRef) => call('GET', `/v1/groups/${encodeURIComponent(groupRef)}`),
+        /** Idempotent: a group ref that does not exist is a no-op. */
+        deleteGroup: (groupRef) => call('DELETE', `/v1/groups/${encodeURIComponent(groupRef)}`),
+        listGroupMembers: (groupRef) => call('GET', `/v1/groups/${encodeURIComponent(groupRef)}/members`).then((r) => r.members),
+        /** Replaces the group's full member list atomically -- never a merge. */
+        setGroupMembers: (groupRef, members) => call('PUT', `/v1/groups/${encodeURIComponent(groupRef)}/members`, { members }).then((r) => r.members),
+        /** Idempotent: a member already present is a no-op. */
+        addGroupMember: (groupRef, member) => call('POST', `/v1/groups/${encodeURIComponent(groupRef)}/members`, member),
+        /** Idempotent: a member not present is a no-op. */
+        removeGroupMember: (groupRef, member) => call('DELETE', `/v1/groups/${encodeURIComponent(groupRef)}/members/${encodeURIComponent(`${member.class}:${member.id}`)}`),
     };
 }
 /** Operator and tenant management routes. `options.fetch` authenticates
@@ -75,6 +140,17 @@ export function createFilesManagementClient(options) {
             return { ...data, created: status === 201 };
         },
         updateOrganisationCeiling: (organisationId, input) => call('PATCH', `/v1/manage/organisations/${encodeURIComponent(organisationId)}`, input),
+        // Delete an organisation with a 7-day grace period (task O, issue #67).
+        // Idempotent: deleting an already-deleted organisation succeeds again
+        // (unchanged `deletedAt`, not a fresh clock); deleting one that was
+        // never provisioned throws `ApiError` with `status: 404`.
+        deleteOrganisation: (organisationId) => call('DELETE', `/v1/manage/organisations/${encodeURIComponent(organisationId)}`),
+        // Undoes deleteOrganisation() within its 7-day grace period; throws
+        // `ApiError` with `status: 404` once that period has passed (whether or
+        // not the organisation has actually been purged yet) or for one that
+        // was never deleted. Requires the same `files.organisations:delete`
+        // permission as deleteOrganisation() -- there is no separate grant.
+        restoreOrganisation: (organisationId) => call('POST', `/v1/manage/organisations/${encodeURIComponent(organisationId)}/restore`),
         // Tenant routes (task S4b): the caller's own organisation, from the
         // signed request's claim -- there is no organisation id to pass here.
         getQuota: () => call('GET', '/v1/manage/quota'),
@@ -94,5 +170,17 @@ export function createFilesManagementClient(options) {
         // Outbound event delivery (task gap-36). setWebhook(null) disables it.
         getWebhook: () => call('GET', '/v1/manage/webhook'),
         setWebhook: (url) => call('PUT', '/v1/manage/webhook', { url }),
+        // Membership (task M): the product that owns its users writes
+        // memberships in its own files organisation. `files.members:read`/
+        // `files.members:update`, held by the calling key for its own
+        // organisation only.
+        listMembers: () => call('GET', '/v1/manage/members'),
+        // Idempotent: adding a subject who is already a member returns their
+        // current row unchanged; use setMemberRole to change it.
+        addMember: (input) => call('POST', '/v1/manage/members', input),
+        setMemberRole: (subject, role) => call('PATCH', `/v1/manage/members/${encodeURIComponent(subject)}`, { role }),
+        // Idempotent: removing a subject who is not (or no longer) a member
+        // still succeeds.
+        removeMember: (subject) => call('DELETE', `/v1/manage/members/${encodeURIComponent(subject)}`),
     };
 }

package/dist/types.d.ts

@@ -1,3 +1,19 @@
+/** Who besides `files.files:read-any` may see a file (issue #71): each entry
+ * is one reference --
+ * - `"org"`: everyone in the organisation who has files read.
+ * - `"person:<subject>"`: one signed-in person.
+ * - `"team:<teamId>"`: members of that authz team whose own
+ *   `files.files:read` grant covers it -- read only, never delete, move,
+ *   replace or share.
+ * - `"group:<app>:<type>/<id>"`, e.g. `"group:chat:room/!abc"`: members of a
+ *   group the named app keeps in sync with files -- also read only.
+ *
+ * The owner is always admitted, whether or not the array names them. Set on
+ * upload (`UploadInput.audience`, default `[]` -- owner only) and changed
+ * afterward with `setFileAudience`; see packages/sdk/README.md's Audience
+ * section for the DM/room/personal-files examples and how groups and
+ * `files.files:read-any` fit in. */
+export type FileAudience = string[];
 /** Public HTTP contracts. Internal object keys and quota rows are never returned. */
 export interface UploadInput {
     collectionId: string;
@@ -25,6 +41,48 @@ export interface UploadInput {
      * is the root. '/'-separated, with no leading, trailing or empty segment.
      * A replacement keeps the file's path. */
     path?: string;
+    /** Who besides `files.files:read-any` may see this file (issue #71).
+     * Omitted defaults to `[]` -- the uploader only, for a person and an app
+     * key alike. Only applies to a brand new file -- a `replace` upload keeps
+     * the target file's existing audience, and must not set this; change it
+     * afterward with `setFileAudience`. */
+    audience?: FileAudience;
+    /** Whether this file can ever back a public share link (issue #71).
+     * Omitted defaults to `false` for a signed-in person, `true` for any
+     * other principal class (an app key), so existing app-key integrations
+     * keep minting links unchanged. Only applies to a brand new file -- a
+     * `replace` upload keeps the target file's existing setting, and must not
+     * set this; change it afterward with `setFileAudience`. */
+    shareable?: boolean;
+}
+/** `copyFile`'s input (task F): copy an existing file's bytes to a brand new
+ * file, in the same collection (the default) or another one in your own
+ * organisation, with an optional new path and/or name. The result is always
+ * a new file id -- never a replace -- and copying a file in another
+ * organisation is simply impossible: the source, if not visible to you,
+ * 404s the same way any other cross-organisation file read does. Variants
+ * and share links are never copied. */
+export interface CopyFileInput {
+    /** Defaults to the source file's own collection. */
+    collectionId?: string;
+    /** Defaults to the source file's own path. */
+    path?: string;
+    /** Defaults to the source file's own name. */
+    name?: string;
+}
+/** `moveFile`'s input (task D): change `path` and/or `name` of an existing
+ * file within its own collection, without re-uploading it. At least one of
+ * `path`/`name` must be given. `version` is the file's current version
+ * (optimistic concurrency, same as a version-pinned read): a stale value
+ * throws `ApiError` with `status: 409`, the same conflict a version-pinned
+ * `getFile`/`downloadFile` already gives. Moving onto a `path`+`name` another
+ * file in the collection already occupies throws the same `409`. */
+export interface MoveFileInput {
+    /** The new folder inside the collection; omitted keeps the current one. */
+    path?: string;
+    /** The new file name; omitted keeps the current one. */
+    name?: string;
+    version: number;
 }
 export interface StoredFile {
     id: string;
@@ -51,6 +109,41 @@ export interface StoredFile {
      * still on record. `null` for a file at version 0 (never confirmed), or
      * when the confirming upload can no longer be found. */
     principalRef: string | null;
+    /** Who besides `files.files:read-any` may see this file (issue #71).
+     * Change it with `setFileAudience`; the owner is always allowed. */
+    audience: FileAudience;
+    /** Whether this file can ever back a public share link (issue #71).
+     * Change it with `setFileAudience`; the owner is always allowed. */
+    shareable: boolean;
+}
+/** A page from `listMyFiles`/`listSharedFiles` (issue #72): newest file
+ * first (`created_at desc`, `id` breaking a tie). `next`, when not `null`,
+ * is an opaque cursor -- pass it back as `after` unchanged for the next
+ * page; `null` means this was the last page. */
+export interface FilesPage {
+    files: StoredFile[];
+    next: string | null;
+}
+/** `listSharedFiles`'s own result row (issue #72): a `StoredFile` the
+ * caller did not upload but may read through its `audience` (issue #71),
+ * plus who owns it -- `listMyFiles`/`getFile` never need this, since the
+ * caller already knows a file is theirs. */
+export interface SharedFile extends StoredFile {
+    owner: {
+        id: string;
+        class: 'human' | 'api_key' | 'agent' | 'service';
+    };
+}
+export interface SharedFilesPage {
+    files: SharedFile[];
+    next: string | null;
+}
+/** `setFileAudience`'s input: `audience` replaces the whole list (not a
+ * merge); `shareable`, omitted, leaves the file's current setting
+ * untouched. */
+export interface SetFileAudienceInput {
+    audience: FileAudience;
+    shareable?: boolean;
 }
 /** Lazily generated image variants (task gap-32), served through
  * `getFileVariant`. A fixed allowlist -- not an arbitrary size -- so a
@@ -149,6 +242,11 @@ export interface OrganisationSummary {
      * organisations: a host another organisation already owns is refused with
      * 409 `conflict`. */
     shareHost: string | null;
+    /** Set by `deleteOrganisation()` (task O, issue #67); `null` for a live
+     * organisation. `restoreOrganisation()` clears it back to `null` within
+     * the 7-day grace period; after that, the organisation and everything it
+     * stored is purged for good and every call answers `not_found`. */
+    deletedAt: string | null;
 }
 export interface ProvisionOrganisationInput {
     organisationId: string;
@@ -156,10 +254,19 @@ export interface ProvisionOrganisationInput {
     ceilingMicros: string | null;
     /** Omitted or `null`: provisioned with no share domain. */
     shareHost?: string | null;
+    /** With `owner`: onboards Agora for the new organisation. */
+    name?: string;
+    /** Subject id of the organisation's first, permanent owner. */
+    owner?: string;
 }
 export interface ProvisionOrganisationResult extends OrganisationSummary {
     /** False when already provisioned: existing ceilings and share host were retained. */
     created: boolean;
+    /** Agora's service key, returned once on a 201 that passed `name` and `owner`. */
+    agoraKey?: {
+        id: string;
+        secret: string;
+    };
 }
 export interface UpdateOrganisationCeilingInput {
     ceilingBytes?: string | null;
@@ -210,9 +317,12 @@ export interface UsageDay {
     rateMicrosPerGbDay: number;
 }
 /** Outbound event delivery (task gap-36): at most one endpoint per
- * organisation, POSTed a signed `files.upload_confirmed` or
- * `files.quota_near_ceiling` event instead of the caller polling. Delivery
- * is best-effort with no retry queue -- a receiver must be idempotent. */
+ * organisation, POSTed a signed `files.upload_confirmed`,
+ * `files.quota_near_ceiling`, `files.file_deleted` or
+ * `files.variant_created` event instead of the caller polling. Delivery
+ * is best-effort with no retry queue -- a receiver must be idempotent. See
+ * packages/sdk/README.md's Webhooks section for each event's payload
+ * shape. */
 export interface WebhookConfig {
     url: string | null;
 }
@@ -224,6 +334,41 @@ export interface SetWebhookResult extends WebhookConfig {
      * header with it. */
     secret: string | null;
 }
+/** Task M (campaign 2026-09-25-agora-files): a membership API for products.
+ * The product that owns its users writes memberships in its own files
+ * organisation -- files never auto-admits a person by token alone. `subject`
+ * is always a person's token subject (a `human` principal). */
+export interface Member {
+    subject: string;
+    /** A role key, e.g. `files_member` (the built-in role, files read/upload/download/share on their own files) or a custom role. */
+    role: string;
+    source: string;
+    grantedBy: string | null;
+    createdAt: string;
+}
+export interface AddMemberInput {
+    subject: string;
+    /** Ignored if `subject` is already a member (`addMember` is idempotent);
+     * use `setMemberRole` to change an existing member's role. */
+    role: string;
+}
+/** Task G (campaign 2026-09-25-agora-files): app-owned groups. An app (chat,
+ * say) creates `group:chat:room/!abc` and keeps its membership in sync as
+ * its own room changes; a file's `audience` (`FileAudience` above) can then
+ * name that group ref to admit its members to a read. Every write here is
+ * refused unless the calling key's own credential names the group ref's own
+ * `<app>` segment (set at `keys:issue --app`, apps/host's README) -- a
+ * human, or a key naming a different app, gets a 403. This ownership rule
+ * is provisional and may change. */
+export type PrincipalClass = 'human' | 'api_key' | 'agent' | 'service';
+export interface GroupMember {
+    class: PrincipalClass;
+    id: string;
+}
+export interface Group {
+    groupRef: string;
+    createdAt: string;
+}
 /** Operator audit filters. Omitted dates select the most recent 92 days. */
 export interface AuditQuery {
     organisation?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/files",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "license": "MIT",
   "description": "Public client SDK and API types for the Files service.",