@fusebase/fusebase-gate-sdk 2.11.6 → 2.11.8-sdk.0

package/dist/apis/FilesApi.d.ts

@@ -5,7 +5,7 @@
  * Domain: files
  */
 import type { Client } from "../runtime/transport";
-import type { CompleteMultipartFileUploadRequestContract, CompleteMultipartFileUploadResponseContract, DeleteFileRequestContract, DeleteFileResponseContract, MultipartUploadIdInPathRequired, orgIdInPathRequired, StartMultipartFileUploadRequestContract, StartMultipartFileUploadResponseContract } from "../types";
+import type { BucketAttachmentContract, BucketAttachmentGlobalIdInPathRequired, CompleteMultipartFileUploadRequestContract, CompleteMultipartFileUploadResponseContract, CreateBucketAttachmentRequestContract, CreateTempStoredFileUploadRequestContract, CreateTempStoredFileUploadResponseContract, DeleteFileRequestContract, DeleteFileResponseContract, ListBucketAttachmentsResponseContract, MultipartUploadIdInPathRequired, orgIdInPathRequired, StartMultipartFileUploadRequestContract, StartMultipartFileUploadResponseContract, UpdateBucketAttachmentRequestContract } from "../types";
 export declare class FilesApi {
     private client;
     constructor(client: Client);
@@ -21,6 +21,28 @@ export declare class FilesApi {
         headers?: Record<string, string>;
         body: CompleteMultipartFileUploadRequestContract;
     }): Promise<CompleteMultipartFileUploadResponseContract>;
+    /**
+     * Create bucket attachment
+     * Turns an uploaded temp stored file into a bucket-service attachment in the organization's `app` bucket, so it shows up in the file listing next to files from notes and portals. Only app tokens can call it: the attachment is owned by the app the token was issued for.
+     */
+    createBucketAttachment(params: {
+        path: {
+            orgId: orgIdInPathRequired;
+        };
+        headers?: Record<string, string>;
+        body: CreateBucketAttachmentRequestContract;
+    }): Promise<BucketAttachmentContract>;
+    /**
+     * Create presigned file upload URL
+     * Returns a presigned URL for uploading a whole file to file-service in one PUT. The client sends only the content-type header returned in `headers` plus the bytes, then passes `tempStoredFileName` on to the operation that creates the record (for example createBucketAttachment). Use startMultipartFileUpload instead for files large enough to need parts.
+     */
+    createTempStoredFileUpload(params: {
+        path: {
+            orgId: orgIdInPathRequired;
+        };
+        headers?: Record<string, string>;
+        body: CreateTempStoredFileUploadRequestContract;
+    }): Promise<CreateTempStoredFileUploadResponseContract>;
     /**
      * Delete file
      * Deletes a file-service stored file by stored-file UUID. Gate never handles the file bytes.
@@ -32,6 +54,25 @@ export declare class FilesApi {
         headers?: Record<string, string>;
         body: DeleteFileRequestContract;
     }): Promise<DeleteFileResponseContract>;
+    /**
+     * List bucket attachments
+     * Lists the organization's files from every source in one list: files uploaded into an app (`app`), note attachments (`note`) and portal files (`portalPage`, `portalGlobal`, `portalFiles`, `portalBlock`). Each item carries its source `target`, the uploader `userId` (resolve the email and role with the org-users operations), the `size` in bytes, the custom `attributes` and the `accessPrincipals`. Filter by source with `targets`, drop small files with `sizeFrom`, and match custom metadata with `attributes`, a JSON object of strings sent as a string, such as `{"source":"file-manager"}`, where every given pair must match exactly (`total` follows the same filter). Clients only receive files their access principals or the bucket permissions allow.
+     */
+    listBucketAttachments(params: {
+        path: {
+            orgId: orgIdInPathRequired;
+        };
+        query?: {
+            targets?: unknown[];
+            sizeFrom?: number;
+            attributes?: string;
+            limit?: number;
+            offset?: number;
+            sortField?: string;
+            sortOrder?: string;
+        };
+        headers?: Record<string, string>;
+    }): Promise<ListBucketAttachmentsResponseContract>;
     /**
      * Start multipart file upload
      * Starts a file-service multipart upload and returns direct PUT URLs. Clients upload each part to the returned URLs, keep each response ETag, and pass those ETags to completeMultipartFileUpload.
@@ -43,4 +84,16 @@ export declare class FilesApi {
         headers?: Record<string, string>;
         body: StartMultipartFileUploadRequestContract;
     }): Promise<StartMultipartFileUploadResponseContract>;
+    /**
+     * Update bucket attachment
+     * Renames a bucket attachment or replaces its attributes and accessPrincipals. Send `accessPrincipals: null` to drop every restriction and show the file to everyone who can see the organization bucket.
+     */
+    updateBucketAttachment(params: {
+        path: {
+            orgId: orgIdInPathRequired;
+            globalId: BucketAttachmentGlobalIdInPathRequired;
+        };
+        headers?: Record<string, string>;
+        body: UpdateBucketAttachmentRequestContract;
+    }): Promise<BucketAttachmentContract>;
 }

package/dist/apis/FilesApi.js

@@ -26,6 +26,36 @@ class FilesApi {
             expectedContentType: "application/json",
         });
     }
+    /**
+     * Create bucket attachment
+     * Turns an uploaded temp stored file into a bucket-service attachment in the organization's `app` bucket, so it shows up in the file listing next to files from notes and portals. Only app tokens can call it: the attachment is owned by the app the token was issued for.
+     */
+    async createBucketAttachment(params) {
+        return this.client.request({
+            method: "POST",
+            path: "/:orgId/bucket-attachments",
+            pathParams: params.path,
+            headers: params.headers,
+            body: params.body,
+            opId: "createBucketAttachment",
+            expectedContentType: "application/json",
+        });
+    }
+    /**
+     * Create presigned file upload URL
+     * Returns a presigned URL for uploading a whole file to file-service in one PUT. The client sends only the content-type header returned in `headers` plus the bytes, then passes `tempStoredFileName` on to the operation that creates the record (for example createBucketAttachment). Use startMultipartFileUpload instead for files large enough to need parts.
+     */
+    async createTempStoredFileUpload(params) {
+        return this.client.request({
+            method: "POST",
+            path: "/:orgId/files/uploads/presigned",
+            pathParams: params.path,
+            headers: params.headers,
+            body: params.body,
+            opId: "createTempStoredFileUpload",
+            expectedContentType: "application/json",
+        });
+    }
     /**
      * Delete file
      * Deletes a file-service stored file by stored-file UUID. Gate never handles the file bytes.
@@ -41,6 +71,21 @@ class FilesApi {
             expectedContentType: "application/json",
         });
     }
+    /**
+     * List bucket attachments
+     * Lists the organization's files from every source in one list: files uploaded into an app (`app`), note attachments (`note`) and portal files (`portalPage`, `portalGlobal`, `portalFiles`, `portalBlock`). Each item carries its source `target`, the uploader `userId` (resolve the email and role with the org-users operations), the `size` in bytes, the custom `attributes` and the `accessPrincipals`. Filter by source with `targets`, drop small files with `sizeFrom`, and match custom metadata with `attributes`, a JSON object of strings sent as a string, such as `{"source":"file-manager"}`, where every given pair must match exactly (`total` follows the same filter). Clients only receive files their access principals or the bucket permissions allow.
+     */
+    async listBucketAttachments(params) {
+        return this.client.request({
+            method: "GET",
+            path: "/:orgId/bucket-attachments",
+            pathParams: params.path,
+            query: params.query,
+            headers: params.headers,
+            opId: "listBucketAttachments",
+            expectedContentType: "application/json",
+        });
+    }
     /**
      * Start multipart file upload
      * Starts a file-service multipart upload and returns direct PUT URLs. Clients upload each part to the returned URLs, keep each response ETag, and pass those ETags to completeMultipartFileUpload.
@@ -56,5 +101,20 @@ class FilesApi {
             expectedContentType: "application/json",
         });
     }
+    /**
+     * Update bucket attachment
+     * Renames a bucket attachment or replaces its attributes and accessPrincipals. Send `accessPrincipals: null` to drop every restriction and show the file to everyone who can see the organization bucket.
+     */
+    async updateBucketAttachment(params) {
+        return this.client.request({
+            method: "PATCH",
+            path: "/:orgId/bucket-attachments/:globalId",
+            pathParams: params.path,
+            headers: params.headers,
+            body: params.body,
+            opId: "updateBucketAttachment",
+            expectedContentType: "application/json",
+        });
+    }
 }
 exports.FilesApi = FilesApi;

package/dist/types/file/file.d.ts

@@ -1,5 +1,6 @@
 export type FileIdInPathRequired = string;
 export type MultipartUploadIdInPathRequired = string;
+export type BucketAttachmentGlobalIdInPathRequired = string;
 export type FileUploadMethodContract = "PUT";
 export interface StartMultipartFileUploadRequestContract {
     filename: string;
@@ -7,6 +8,95 @@ export interface StartMultipartFileUploadRequestContract {
     contentType?: string | null;
     folder?: string | null;
 }
+export interface CreateTempStoredFileUploadRequestContract {
+    name: string;
+    type?: string | null;
+    size?: number | null;
+    folder?: string | null;
+    public?: boolean | null;
+}
+/**
+ * Who may see an app file. Null means everyone who can see the org bucket.
+ */
+export interface BucketAttachmentAccessPrincipalsContract {
+    roles?: string[] | null;
+    userIds?: number[] | null;
+    /** Organization group global ids. */
+    groupIds?: string[] | null;
+}
+/**
+ * Custom key/value metadata set by the uploader (max 50 keys, key and value max
+ * 255 chars).
+ */
+export type BucketAttachmentAttributesContract = Record<string, string>;
+export interface CreateBucketAttachmentRequestContract {
+    /**
+     * Name returned by createTempStoredFileUpload or completeMultipartFileUpload.
+     */
+    tempStoredFileName: string;
+    attributes?: BucketAttachmentAttributesContract | null;
+    accessPrincipals?: BucketAttachmentAccessPrincipalsContract | null;
+    folder?: string | null;
+}
+export interface UpdateBucketAttachmentRequestContract {
+    filename?: string | null;
+    /**
+     * Replaces the whole attributes object when present.
+     */
+    attributes?: BucketAttachmentAttributesContract | null;
+    /**
+     * Null clears every principal, so the file goes back to everyone who can see
+     * the org bucket. Absent leaves the access principals untouched.
+     */
+    accessPrincipals?: BucketAttachmentAccessPrincipalsContract | null;
+}
+/**
+ * Bucket permissions of a note or portal file, as bucket-service stores them.
+ * Only returned to organization members, never to clients.
+ */
+export interface BucketAttachmentPermissionsContract {
+    allowAll: boolean;
+    rejectAll: boolean;
+    allowUserIds: number[];
+    rejectUserIds: number[];
+}
+export interface BucketAttachmentContract {
+    globalId: string;
+    /**
+     * Source bucket of the file: `app` for files uploaded into the app itself,
+     * `note` or `portal` for files that came from elsewhere in the organization.
+     */
+    target: string;
+    targetId: string;
+    filename: string;
+    type: string;
+    size: number;
+    /**
+     * Fusebase user id of the uploader.
+     */
+    userId: number;
+    /**
+     * @format uri
+     */
+    url: string;
+    createdAt: number;
+    attributes: BucketAttachmentAttributesContract | null;
+    accessPrincipals: BucketAttachmentAccessPrincipalsContract | null;
+    /**
+     * Workspace the file came from, for note and portal files.
+     */
+    workspaceId?: string | null;
+    portalId?: string | null;
+    permissions?: BucketAttachmentPermissionsContract | null;
+}
+export interface ListBucketAttachmentsResponseContract {
+    items: BucketAttachmentContract[];
+    /**
+     * Number of files matching the filters, counted by bucket-service. Capped at
+     * 1000.
+     */
+    total: number;
+}
 export interface DeleteFileRequestContract {
     fileId: string;
 }
@@ -40,6 +130,23 @@ export interface StartMultipartFileUploadResponseContract {
     tempStoredfileName: string;
     partNumber: number;
 }
+export interface CreateTempStoredFileUploadResponseContract {
+    tempStoredFileName: string;
+    /**
+     * @format uri
+     */
+    uploadUrl: string;
+    method: FileUploadMethodContract;
+    /**
+     * Unix timestamp in seconds after which the upload URL stops working.
+     */
+    expiresAt: number;
+    /**
+     * The only headers the direct PUT may carry. The URL signs `host` alone, so
+     * sending anything beyond `content-type` breaks the signature.
+     */
+    headers: FileUploadHeadersContract;
+}
 export interface CompleteMultipartFileUploadPartContract {
     etag: string;
     partNumber: number;
@@ -49,10 +156,26 @@ export interface CompleteMultipartFileUploadRequestContract {
     parts: CompleteMultipartFileUploadPartContract[];
     contentType?: string | null;
     folder?: string | null;
+    /**
+     * Create the stored-file record after finishing the upload. Defaults to true.
+     * Set to false to keep the result as a temp stored file only.
+     */
+    saveStoredFile?: boolean | null;
 }
 export interface CompleteMultipartFileUploadResponseContract {
-    fileId: string;
-    storedFileUUID: string;
+    /**
+     * Null when `saveStoredFile` was false.
+     */
+    fileId: string | null;
+    /**
+     * Null when `saveStoredFile` was false.
+     */
+    storedFileUUID: string | null;
+    /**
+     * Whether the stored-file record was created.
+     */
+    storedFileCreated: boolean;
+    tempStoredFileName: string;
     /**
      * File-service public object name returned by finish multipart upload.
      */

package/dist/types/orgs/orgs.d.ts

@@ -3,7 +3,7 @@ export interface OrgUrlResponseContract {
     orgId: string;
     /** Canonical HTTPS base URL for the organization (no trailing path). */
     url: string;
-    /** Hostname used in `url` (custom CNAME domain or `{sub}.{fusebaseHost}`). */
+    /** Hostname used in `url` (custom CNAME domain or `{sub}.{fusebaseWebClientHost}`). */
     host: string;
     /** `cname` when the org uses a custom domain; otherwise `subdomain`. */
     kind: OrgUrlKindContract;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusebase/fusebase-gate-sdk",
-  "version": "2.11.6",
+  "version": "2.11.8-sdk.0",
   "description": "TypeScript SDK for Fusebase Gate APIs - Generated from contract introspection",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/release-notes/2.11.8-sdk.0.md

@@ -0,0 +1,252 @@
+# Release Notes 2.11.8-sdk.0
+
+- Current ref: `HEAD`
+- Previous tag: `v2.11.7-sdk.0`
+- Generated at: 2026-09-21T07:25:49.110Z
+
+## Included Drafts
+
+- `docs/release-notes/2026-06-08-get-org-url.md` - Get organization URL
+- `docs/release-notes/2026-09-09-org-url-web-client-host.md` - getOrgUrl returns the web-client host
+- `docs/release-notes/2026-09-14-bucket-attachments.md` - Bucket attachments for app files
+- `docs/release-notes/2026-09-14-list-bucket-attachments.md` - One file list across app, note and portal files
+- `docs/release-notes/2026-09-14-presigned-file-upload.md` - Presigned single-request file upload
+- `docs/release-notes/2026-09-19-web-studio-motion-guidance.md` - Web Studio motion guidance
+
+## Summary
+
+### Get organization URL
+
+Gate exposes `GET /:orgId/url` (`getOrgUrl`) to resolve the canonical HTTPS base URL for an organization. The hostname follows org-service rules: custom CNAME domain when configured, otherwise `{sub}.{FUSEBASE_WEB_CLIENT_HOST}` (see the 2026-09-09 note; before that it was `{sub}.{FUSEBASE_HOST}`).
+
+### getOrgUrl returns the web-client host
+
+`getOrgUrl` built org subdomain URLs from `FUSEBASE_HOST` (the API host, e.g.
+`thefusebase.com`), so it returned `{sub}.thefusebase.com`. Users know their org by
+the web-client host (`{sub}.nimbusweb.me` on prod). Both hosts resolve, so the wrong
+one never failed loudly.
+
+`FUSEBASE_HOST` could not be repurposed — it also derives `app.thefusebase.com` for
+the auth-form URLs.
+
+### Bucket attachments for app files
+
+An app that uploaded a file through Gate had nowhere to put it: the stored file was
+not part of the organization's file listing, so the File Manager app could only ever
+show its own files. Gate now talks to bucket-service, so an uploaded file becomes an
+attachment in the organization's `app` bucket and shows up next to files from notes
+and portals.
+
+### One file list across app, note and portal files
+
+The File Manager app could only show the files it uploaded itself. `listBucketAttachments`
+returns the organization's files from every source in one list, with the metadata needed to
+filter them (source, uploader, size) and to show each file only to people who may see it.
+
+### Presigned single-request file upload
+
+Uploading a file through Gate always meant a multipart upload: start, PUT every part,
+complete. For a file small enough to fit in one request that is three round trips for
+no reason, and the completion step always created a stored-file record, which the
+File Manager app does not want — it creates its own bucket attachment instead.
+
+### Web Studio motion guidance
+
+Added the safe, declarative Web Studio motion contract to the Gate MCP prompt.
+
+
+## API / SDK Changes
+
+### Get organization URL
+
+- Added `getOrgUrl` operation and `OrgsApi.getOrgUrl` SDK client method.
+- Response fields: `url`, `host`, `kind` (`cname` | `subdomain`), `sub`, `customDomain`, `domainShorter`.
+- Permission: `org.read` with org-scoped authz.
+
+### Bucket attachments for app files
+
+- New op `createBucketAttachment`, `POST /:orgId/bucket-attachments` (`files.write`).
+  Body takes `tempStoredFileName` (required) plus optional `attributes`, `accessPrincipals`
+  and `folder`. Gate generates the attachment id and reads the owning app from the
+  token's `client` scope, so a call without an app token answers 400.
+- New op `updateBucketAttachment`, `PATCH /:orgId/bucket-attachments/:globalId`
+  (`files.write`). Body takes `filename`, `attributes` and `accessPrincipals`, all optional.
+  A field that is not sent stays as it is; `accessPrincipals: null` clears every
+  restriction. bucket-service statuses (400, 404) are passed through unchanged.
+- Both return the attachment as `globalId`, `target`, `targetId`, `filename`, `type`,
+  `size`, `userId`, `url`, `createdAt`, `attributes` and `accessPrincipals`.
+- MCP `files` prompt covers both ops, and the Gate files skill reference is
+  regenerated.
+
+### One file list across app, note and portal files
+
+- New op `listBucketAttachments`, `GET /:orgId/bucket-attachments` (`files.read`, clients
+  included). Query: `targets` (source buckets, for example `app` or `note`), `sizeFrom`
+  (bytes), `attributes`, `limit` (default 50, max 100), `offset`, `sortField`, `sortOrder`.
+- `attributes` keeps only the files whose custom metadata contains every given pair, as a
+  JSON object of strings such as `{"source":"file-manager"}` (max 50 keys, 255 chars per key
+  and value). `total` follows the same filter. A malformed filter is a 400, answered before
+  bucket-service is called.
+- Returns `{items, total}`. Each item carries `globalId`, `target` (the source), `targetId`,
+  `workspaceId`, `portalId`, `filename`, `type`, `size`, `userId` (the uploader), `url`,
+  `createdAt`, `attributes`, `accessPrincipals` and, for organization members, `permissions`.
+- `createBucketAttachment` and `updateBucketAttachment` now return the same three extra
+  fields (`workspaceId`, `portalId`, `permissions`), null for app files.
+- Gate resolves the caller's organization role and group memberships itself and forwards
+  them, with the caller's user id, to both the listing and the count. bucket-service then
+  decides what the caller may see. A client role is filtered in `client` permissions mode,
+  everyone else in `admin` mode.
+- `accessPrincipals.groupIds` on `createBucketAttachment` and `updateBucketAttachment` are
+  organization group global ids (strings), the ids org-service and bucket-service use.
+- MCP `files` prompt covers the new op, and the Gate files skill reference is regenerated.
+
+### Presigned single-request file upload
+
+- New op `createTempStoredFileUpload`, `POST /:orgId/files/uploads/presigned`
+  (`files.write`). Body takes `name` (required) plus optional `type`, `size`,
+  `folder` and `public`. It returns `uploadUrl`, `method`, `expiresAt`,
+  `tempStoredFileName`, and `headers` holding the single `content-type` header the
+  PUT may carry — the URL signs `host` only, so anything else breaks the signature.
+- `completeMultipartFileUpload` takes an optional `saveStoredFile` (default `true`).
+  With `false` it finishes the upload and skips the stored-file record.
+- `completeMultipartFileUpload` response gains `storedFileCreated` and
+  `tempStoredfileName`. `fileId` and `storedFileUUID` are now nullable — they are
+  null exactly when `saveStoredFile` was `false`.
+- MCP `files` prompt covers both, and the Gate files skill reference is regenerated.
+
+### Web Studio motion guidance
+
+No operation or SDK contract changed. The `webStudio` MCP prompt is now version
+`1.11.0` and describes the supported `reveal`, `count`, and `parallax` motion
+attributes and their bounded options.
+
+
+## Consumer Impact
+
+### Get organization URL
+
+- Apps and agents can stop hardcoding Fusebase hostnames when building org-scoped links.
+- Portal domains and app magic-link hosts remain separate surfaces; use `listPortals` or app APIs for those.
+
+### getOrgUrl returns the web-client host
+
+- Custom CNAME domains are unchanged — they already won over the host.
+- Deployments without the new variable keep the previous behaviour via the fallback.
+
+### Bucket attachments for app files
+
+- Nothing changes for existing callers: both ops are new and no existing response
+  shape moved.
+- Deployments need `BUCKET_SERVICE_URL`. Without it the two new ops answer 500 and
+  every other op is unaffected.
+- Gate calls bucket-service with the plain `Internal` header and no super secret, so
+  bucket-service authorizes the real user against the file's own organization. That
+  is what keeps an app from touching an attachment in another organization.
+
+### One file list across app, note and portal files
+
+- Nothing changes for existing callers: the op is new and the two added fields are optional.
+- A token issued for an app sees exactly what a user session for the same user sees: the
+  role and the group memberships are resolved from the organization membership and from
+  org-service, not from the request.
+- `total` is counted by bucket-service, which counts the page it would return, so the gate
+  asks it for up to 1000 files. A larger organization reports 1000.
+
+### Presigned single-request file upload
+
+- Existing callers are unaffected: `saveStoredFile` defaults to `true`, so the
+  response keeps the same values it had.
+- TypeScript consumers reading `storedFileUUID` from the completion response now see
+  `string | null` and have to narrow it. Checking `storedFileCreated` is the clearest
+  way.
+
+### Web Studio motion guidance
+
+MCP agents receive the same motion guidance as Studio Chat: they can request
+compiler-owned motion without attempting to add site-authored JavaScript.
+
+
+## Verification
+
+### Get organization URL
+
+- `npm test -- tests/unit/org-url-service.test.ts tests/unit/orgs-controller.test.ts`
+- `npm run build:sdk`
+- `npm run mcp:skills:generate`
+- `npm run mcp:skills:validate`
+
+### getOrgUrl returns the web-client host
+
+- `npm test -- tests/unit/config-env.test.ts tests/unit/orgs-controller.test.ts tests/unit/org-url-service.test.ts`
+
+### Bucket attachments for app files
+
+- `npm test -- tests/unit/files`
+- `npm run build`, `npm run build:sdk`, `npm run mcp:skills:generate`,
+  `npm run mcp:skills:validate`
+- e2e-sdk and mcp-e2e cover the update flow and the 400/404 cases against a fake
+  bucket-service. Creating an attachment needs a real app token (`client` scope),
+  so that path is covered by unit tests and by QA on dev (NIM-44491).
+
+### One file list across app, note and portal files
+
+- `npm test -- tests/unit/files tests/unit/bucket-service-client`
+- `npm run build`, `npm run build:sdk`, `npm run mcp:skills:generate`,
+  `npm run mcp:skills:validate`
+- e2e-sdk and mcp-e2e list app and note files against the fake bucket-service and check the
+  `targets` and `sizeFrom` filters. The fake enforces the caller access principals, and one
+  e2e-sdk case creates a real group, grants files by role and by group, and asserts both
+  a token and a user session see them while a file granted to neither stays hidden. Further
+  cases cover the `attributes` filter and its count, an app file addressed to another user
+  staying hidden from an org member, the uploader receiving their own restricted file, and a
+  client receiving the app file granted to the `client` role.
+
+### Presigned single-request file upload
+
+- `npm test -- tests/unit/files`
+- `npm run build`, `npm run build:sdk`, `npm run mcp:skills:generate`,
+  `npm run mcp:skills:validate`
+
+### Web Studio motion guidance
+
+- `npm run build`
+- `npm run mcp:skills:generate`
+- `npm run mcp:skills:validate` remains blocked locally because the `skills_ref`
+  Python module is unavailable.
+
+
+## Follow-ups
+
+### Get organization URL
+
+- None.
+
+### Bucket attachments for app files
+
+- `listBucketAttachments` (NIM-44489) returns the aggregated listing these
+  attachments join.
+
+### Presigned single-request file upload
+
+- `createBucketAttachment` (NIM-44488) is what turns `tempStoredFileName` into a
+  bucket attachment for the File Manager app.
+
+### Web Studio motion guidance
+
+Deploy the matching Web Studio compiler release before relying on motion
+attributes in published sites.
+
+
+## Changes
+
+### getOrgUrl returns the web-client host
+
+- New env variable `FUSEBASE_WEB_CLIENT_HOST` (`config.fusebaseWebClientHost`),
+  falling back to `FUSEBASE_HOST` when unset.
+- `getOrgUrl` now resolves subdomain org URLs against `fusebaseWebClientHost`, and so
+  do the markdown-note share URLs, which are built on the same org base.
+- The MCP prompt host bag carries `fusebaseWebClientHost` alongside `fusebaseHost`;
+  the `getOrgUrl` prompt example uses the web-client one. `fusebaseHost` keeps meaning
+  the API/platform host everywhere.
+- Added to nimbus-helm-chart `fusebase-gate` values and deployment env
+  (prod `nimbusweb.me`, dev `dev-thefusebase.com`).

package/release-notes/latest.md

@@ -1,9 +1,252 @@
-# Release Notes 2.11.6
+# Release Notes 2.11.8-sdk.0
 
 - Current ref: `HEAD`
-- Previous tag: `v2.11.6`
-- Generated at: 2026-09-09T09:28:57.596Z
+- Previous tag: `v2.11.7-sdk.0`
+- Generated at: 2026-09-21T07:25:49.110Z
 
 ## Included Drafts
 
-- None
+- `docs/release-notes/2026-06-08-get-org-url.md` - Get organization URL
+- `docs/release-notes/2026-09-09-org-url-web-client-host.md` - getOrgUrl returns the web-client host
+- `docs/release-notes/2026-09-14-bucket-attachments.md` - Bucket attachments for app files
+- `docs/release-notes/2026-09-14-list-bucket-attachments.md` - One file list across app, note and portal files
+- `docs/release-notes/2026-09-14-presigned-file-upload.md` - Presigned single-request file upload
+- `docs/release-notes/2026-09-19-web-studio-motion-guidance.md` - Web Studio motion guidance
+
+## Summary
+
+### Get organization URL
+
+Gate exposes `GET /:orgId/url` (`getOrgUrl`) to resolve the canonical HTTPS base URL for an organization. The hostname follows org-service rules: custom CNAME domain when configured, otherwise `{sub}.{FUSEBASE_WEB_CLIENT_HOST}` (see the 2026-09-09 note; before that it was `{sub}.{FUSEBASE_HOST}`).
+
+### getOrgUrl returns the web-client host
+
+`getOrgUrl` built org subdomain URLs from `FUSEBASE_HOST` (the API host, e.g.
+`thefusebase.com`), so it returned `{sub}.thefusebase.com`. Users know their org by
+the web-client host (`{sub}.nimbusweb.me` on prod). Both hosts resolve, so the wrong
+one never failed loudly.
+
+`FUSEBASE_HOST` could not be repurposed — it also derives `app.thefusebase.com` for
+the auth-form URLs.
+
+### Bucket attachments for app files
+
+An app that uploaded a file through Gate had nowhere to put it: the stored file was
+not part of the organization's file listing, so the File Manager app could only ever
+show its own files. Gate now talks to bucket-service, so an uploaded file becomes an
+attachment in the organization's `app` bucket and shows up next to files from notes
+and portals.
+
+### One file list across app, note and portal files
+
+The File Manager app could only show the files it uploaded itself. `listBucketAttachments`
+returns the organization's files from every source in one list, with the metadata needed to
+filter them (source, uploader, size) and to show each file only to people who may see it.
+
+### Presigned single-request file upload
+
+Uploading a file through Gate always meant a multipart upload: start, PUT every part,
+complete. For a file small enough to fit in one request that is three round trips for
+no reason, and the completion step always created a stored-file record, which the
+File Manager app does not want — it creates its own bucket attachment instead.
+
+### Web Studio motion guidance
+
+Added the safe, declarative Web Studio motion contract to the Gate MCP prompt.
+
+
+## API / SDK Changes
+
+### Get organization URL
+
+- Added `getOrgUrl` operation and `OrgsApi.getOrgUrl` SDK client method.
+- Response fields: `url`, `host`, `kind` (`cname` | `subdomain`), `sub`, `customDomain`, `domainShorter`.
+- Permission: `org.read` with org-scoped authz.
+
+### Bucket attachments for app files
+
+- New op `createBucketAttachment`, `POST /:orgId/bucket-attachments` (`files.write`).
+  Body takes `tempStoredFileName` (required) plus optional `attributes`, `accessPrincipals`
+  and `folder`. Gate generates the attachment id and reads the owning app from the
+  token's `client` scope, so a call without an app token answers 400.
+- New op `updateBucketAttachment`, `PATCH /:orgId/bucket-attachments/:globalId`
+  (`files.write`). Body takes `filename`, `attributes` and `accessPrincipals`, all optional.
+  A field that is not sent stays as it is; `accessPrincipals: null` clears every
+  restriction. bucket-service statuses (400, 404) are passed through unchanged.
+- Both return the attachment as `globalId`, `target`, `targetId`, `filename`, `type`,
+  `size`, `userId`, `url`, `createdAt`, `attributes` and `accessPrincipals`.
+- MCP `files` prompt covers both ops, and the Gate files skill reference is
+  regenerated.
+
+### One file list across app, note and portal files
+
+- New op `listBucketAttachments`, `GET /:orgId/bucket-attachments` (`files.read`, clients
+  included). Query: `targets` (source buckets, for example `app` or `note`), `sizeFrom`
+  (bytes), `attributes`, `limit` (default 50, max 100), `offset`, `sortField`, `sortOrder`.
+- `attributes` keeps only the files whose custom metadata contains every given pair, as a
+  JSON object of strings such as `{"source":"file-manager"}` (max 50 keys, 255 chars per key
+  and value). `total` follows the same filter. A malformed filter is a 400, answered before
+  bucket-service is called.
+- Returns `{items, total}`. Each item carries `globalId`, `target` (the source), `targetId`,
+  `workspaceId`, `portalId`, `filename`, `type`, `size`, `userId` (the uploader), `url`,
+  `createdAt`, `attributes`, `accessPrincipals` and, for organization members, `permissions`.
+- `createBucketAttachment` and `updateBucketAttachment` now return the same three extra
+  fields (`workspaceId`, `portalId`, `permissions`), null for app files.
+- Gate resolves the caller's organization role and group memberships itself and forwards
+  them, with the caller's user id, to both the listing and the count. bucket-service then
+  decides what the caller may see. A client role is filtered in `client` permissions mode,
+  everyone else in `admin` mode.
+- `accessPrincipals.groupIds` on `createBucketAttachment` and `updateBucketAttachment` are
+  organization group global ids (strings), the ids org-service and bucket-service use.
+- MCP `files` prompt covers the new op, and the Gate files skill reference is regenerated.
+
+### Presigned single-request file upload
+
+- New op `createTempStoredFileUpload`, `POST /:orgId/files/uploads/presigned`
+  (`files.write`). Body takes `name` (required) plus optional `type`, `size`,
+  `folder` and `public`. It returns `uploadUrl`, `method`, `expiresAt`,
+  `tempStoredFileName`, and `headers` holding the single `content-type` header the
+  PUT may carry — the URL signs `host` only, so anything else breaks the signature.
+- `completeMultipartFileUpload` takes an optional `saveStoredFile` (default `true`).
+  With `false` it finishes the upload and skips the stored-file record.
+- `completeMultipartFileUpload` response gains `storedFileCreated` and
+  `tempStoredfileName`. `fileId` and `storedFileUUID` are now nullable — they are
+  null exactly when `saveStoredFile` was `false`.
+- MCP `files` prompt covers both, and the Gate files skill reference is regenerated.
+
+### Web Studio motion guidance
+
+No operation or SDK contract changed. The `webStudio` MCP prompt is now version
+`1.11.0` and describes the supported `reveal`, `count`, and `parallax` motion
+attributes and their bounded options.
+
+
+## Consumer Impact
+
+### Get organization URL
+
+- Apps and agents can stop hardcoding Fusebase hostnames when building org-scoped links.
+- Portal domains and app magic-link hosts remain separate surfaces; use `listPortals` or app APIs for those.
+
+### getOrgUrl returns the web-client host
+
+- Custom CNAME domains are unchanged — they already won over the host.
+- Deployments without the new variable keep the previous behaviour via the fallback.
+
+### Bucket attachments for app files
+
+- Nothing changes for existing callers: both ops are new and no existing response
+  shape moved.
+- Deployments need `BUCKET_SERVICE_URL`. Without it the two new ops answer 500 and
+  every other op is unaffected.
+- Gate calls bucket-service with the plain `Internal` header and no super secret, so
+  bucket-service authorizes the real user against the file's own organization. That
+  is what keeps an app from touching an attachment in another organization.
+
+### One file list across app, note and portal files
+
+- Nothing changes for existing callers: the op is new and the two added fields are optional.
+- A token issued for an app sees exactly what a user session for the same user sees: the
+  role and the group memberships are resolved from the organization membership and from
+  org-service, not from the request.
+- `total` is counted by bucket-service, which counts the page it would return, so the gate
+  asks it for up to 1000 files. A larger organization reports 1000.
+
+### Presigned single-request file upload
+
+- Existing callers are unaffected: `saveStoredFile` defaults to `true`, so the
+  response keeps the same values it had.
+- TypeScript consumers reading `storedFileUUID` from the completion response now see
+  `string | null` and have to narrow it. Checking `storedFileCreated` is the clearest
+  way.
+
+### Web Studio motion guidance
+
+MCP agents receive the same motion guidance as Studio Chat: they can request
+compiler-owned motion without attempting to add site-authored JavaScript.
+
+
+## Verification
+
+### Get organization URL
+
+- `npm test -- tests/unit/org-url-service.test.ts tests/unit/orgs-controller.test.ts`
+- `npm run build:sdk`
+- `npm run mcp:skills:generate`
+- `npm run mcp:skills:validate`
+
+### getOrgUrl returns the web-client host
+
+- `npm test -- tests/unit/config-env.test.ts tests/unit/orgs-controller.test.ts tests/unit/org-url-service.test.ts`
+
+### Bucket attachments for app files
+
+- `npm test -- tests/unit/files`
+- `npm run build`, `npm run build:sdk`, `npm run mcp:skills:generate`,
+  `npm run mcp:skills:validate`
+- e2e-sdk and mcp-e2e cover the update flow and the 400/404 cases against a fake
+  bucket-service. Creating an attachment needs a real app token (`client` scope),
+  so that path is covered by unit tests and by QA on dev (NIM-44491).
+
+### One file list across app, note and portal files
+
+- `npm test -- tests/unit/files tests/unit/bucket-service-client`
+- `npm run build`, `npm run build:sdk`, `npm run mcp:skills:generate`,
+  `npm run mcp:skills:validate`
+- e2e-sdk and mcp-e2e list app and note files against the fake bucket-service and check the
+  `targets` and `sizeFrom` filters. The fake enforces the caller access principals, and one
+  e2e-sdk case creates a real group, grants files by role and by group, and asserts both
+  a token and a user session see them while a file granted to neither stays hidden. Further
+  cases cover the `attributes` filter and its count, an app file addressed to another user
+  staying hidden from an org member, the uploader receiving their own restricted file, and a
+  client receiving the app file granted to the `client` role.
+
+### Presigned single-request file upload
+
+- `npm test -- tests/unit/files`
+- `npm run build`, `npm run build:sdk`, `npm run mcp:skills:generate`,
+  `npm run mcp:skills:validate`
+
+### Web Studio motion guidance
+
+- `npm run build`
+- `npm run mcp:skills:generate`
+- `npm run mcp:skills:validate` remains blocked locally because the `skills_ref`
+  Python module is unavailable.
+
+
+## Follow-ups
+
+### Get organization URL
+
+- None.
+
+### Bucket attachments for app files
+
+- `listBucketAttachments` (NIM-44489) returns the aggregated listing these
+  attachments join.
+
+### Presigned single-request file upload
+
+- `createBucketAttachment` (NIM-44488) is what turns `tempStoredFileName` into a
+  bucket attachment for the File Manager app.
+
+### Web Studio motion guidance
+
+Deploy the matching Web Studio compiler release before relying on motion
+attributes in published sites.
+
+
+## Changes
+
+### getOrgUrl returns the web-client host
+
+- New env variable `FUSEBASE_WEB_CLIENT_HOST` (`config.fusebaseWebClientHost`),
+  falling back to `FUSEBASE_HOST` when unset.
+- `getOrgUrl` now resolves subdomain org URLs against `fusebaseWebClientHost`, and so
+  do the markdown-note share URLs, which are built on the same org base.
+- The MCP prompt host bag carries `fusebaseWebClientHost` alongside `fusebaseHost`;
+  the `getOrgUrl` prompt example uses the web-client one. `fusebaseHost` keeps meaning
+  the API/platform host everywhere.
+- Added to nimbus-helm-chart `fusebase-gate` values and deployment env
+  (prod `nimbusweb.me`, dev `dev-thefusebase.com`).

package/release-notes/2.11.6-sdk.0.md

@@ -1,61 +0,0 @@
-# Release Notes 2.11.6-sdk.0
-
-- Current ref: `HEAD`
-- Previous tag: `v2.11.6-sdk.0`
-- Generated at: 2026-09-08T12:29:57.106Z
-
-## Included Drafts
-
-- `docs/release-notes/2026-09-07-app-auth-handoff.md` - Login handoff for the fusebase-auth ops
-
-## Summary
-
-### Login handoff for the fusebase-auth ops
-
-The four fusebase-auth operations that can end in an authenticated result now
-return an `appAuth` handoff beside `session`, so an app can obtain its own
-runtime token without holding a raw FuseBase session id.
-
-
-## API / SDK Changes
-
-### Login handoff for the fusebase-auth ops
-
-- Added `appAuth` (`exchangeToken`, `expiresInSeconds`, `authPath`) to the
-  authenticated responses of `registerFusebaseUser`,
-  `registerFusebaseOrgMember`, `loginFusebaseUser` and
-  `completeFusebaseAuthChallenge`.
-- `authPath` is a relative URL on the app's own host, built from the
-  `redirectPath` the app sent. Apps pass it through rather than assembling it.
-- Operation descriptions now point at the handoff instead of at
-  `session.sessionId`.
-- `session` is deprecated. Gate omits it from all four responses when it runs
-  with the `app_login_no_session_id` feature flag, which is off everywhere
-  until deployed apps have moved to `appAuth`.
-- With that flag on, a failed handoff mint answers 422 with `data.errorCode` =
-  `app_auth_exchange_unavailable` instead of degrading to the legacy response.
-
-
-## Consumer Impact
-
-### Login handoff for the fusebase-auth ops
-
-Purely additive: `session` is returned exactly as before, so no deployed app
-changes behaviour. Spend `appAuth.authPath` on the app's own origin, either
-with a same-origin `fetch` sending `Accept: application/json` or with a plain
-navigation. `exchangeToken` stays valid for its whole `expiresInSeconds`
-window, is not invalidated by being spent, and is not bound to the app it was
-minted for, so treat it as a credential.
-A challenge result is unchanged. If the mint fails the response is the legacy
-one, without `appAuth` — until the `app_login_no_session_id` flag is turned on,
-where the same failure is a 422 that should be answered with a fresh sign-in
-rather than a replay of the call.
-
-
-## Verification
-
-### Login handoff for the fusebase-auth ops
-
-- Unit tests over all four operations, the handoff URL encoding, the mint
-  failure paths and the relative-path guard.
-- Generated contract/OpenAPI validation and service build.

package/release-notes/2.11.6.md

@@ -1,9 +0,0 @@
-# Release Notes 2.11.6
-
-- Current ref: `HEAD`
-- Previous tag: `v2.11.6`
-- Generated at: 2026-09-09T09:28:57.596Z
-
-## Included Drafts
-
-- None