@north-light/sdk 0.3.658 → 0.3.660

package/dist/client.d.ts

@@ -74,15 +74,15 @@ export interface CrouterOptions {
 }
 /** The namespaces of `Crouter` that only the owner's own daemon serves. A person's app listener answers them `404 unknown operation`. */
 export type OwnerOnly = 'spendLimits' | 'nodes' | 'bash' | 'canvas' | 'crons' | 'structuredRequests' | 'customObjects' | 'human' | 'models' | 'system' | 'auth';
-/** What an app reaches on a person's runtime (the app listener): `Crouter` without the owner-daemon namespaces, `files.download`
+/** What an app reaches on a person's runtime (the app listener): `Crouter` without the owner-daemon namespaces, `files.link` and `files.download`
  *  only, `profiles.list` only, `customObjects` register/publish/unregister and `canvas` watch/unwatch. `Crouter` is assignable to it, so a function that takes `AppClient` takes either. */
 export type AppClient = Omit<Crouter, OwnerOnly | 'files' | 'profiles'> & {
     /** Register, publish to and unregister the custom objects the app owns (`receive` and `ack` are owner-daemon only). */
     readonly customObjects: Pick<CustomObjects, 'register' | 'publish' | 'unregister'>;
     /** Link nodes to the app's objects: `watch` and `unwatch` with `watcher` (and `watcher_machine` for a node of another machine), under `crtr:objects:link:node`. */
     readonly canvas: Pick<Canvas, 'watch' | 'unwatch'>;
-    /** Download a file the person's runtime holds (`files.download`); the other `files` calls are owner-daemon only. */
-    readonly files: Pick<Files, 'download'>;
+    /** Download a file the person's runtime holds by path (`files.download`) or an agent-handed file by its id (`files.link`); the other `files` calls are owner-daemon only. */
+    readonly files: Pick<Files, 'download' | 'link'>;
     /** The profiles the app may start runs with (`profiles.list`); `ensure` and `retrieve` are owner-daemon only. */
     readonly profiles: Pick<Crouter['profiles'], 'list'>;
 };

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export type { RunEvent, RunEventListener, RunEventOf, RunEventType, RunStreamEnd
 export { RunReply } from './resources/run-reply.js';
 export type { RunReplyCollectOptions, RunReplyEnding, RunReplyEvent, RunReplyResult, SentRunMessage } from './resources/run-reply.js';
 export type { AppProfile, RunActivity, RunDeleteResult, RunObject, RunParsedOutcome, RunParseOptions, RunParseParams, RunRecap, RunStartParams, RunStartResult, RunStatus, RunTrace } from './resources/runs.js';
-export type { FileDownloadOptions } from './resources/files.js';
+export type { FileDownloadOptions, FileLink } from './resources/files.js';
 export type { Upload, UploadCreateParams } from './resources/uploads.js';
 export type { AttachmentLink } from './resources/attachments.js';
 export type { Share, ShareCreated, ShareCreateParams } from './resources/shares.js';

package/dist/oauth/index.d.ts

@@ -110,7 +110,7 @@ declare const AppCrouter: new (options: CrouterOptions) => AppClient;
 /** A runtime client on one person's stored connection (`oauth.client(userId)`): an `AppClient` that refreshes its
  *  token through the `OAuth2Client`'s store, plus whose connection it is and the runtime it calls. It offers only what
  *  the person's app listener serves. The owner-daemon namespaces (`nodes`, `crons`, …) are absent from its
- *  type and throw `CrouterError` if reached anyway; `files` is `download` only, `profiles` is `list` only, `customObjects` is
+ *  type and throw `CrouterError` if reached anyway; `files` is `download` and `link` only, `profiles` is `list` only, `customObjects` is
  *  `register`, `publish` and `unregister`, and `canvas` is `watch` and `unwatch`.
  *  `request` still sends any route. */
 export declare class ConnectedCrouter extends AppCrouter {

package/dist/oauth/index.js

@@ -70,7 +70,7 @@ const AppCrouter = Crouter;
 /** A runtime client on one person's stored connection (`oauth.client(userId)`): an `AppClient` that refreshes its
  *  token through the `OAuth2Client`'s store, plus whose connection it is and the runtime it calls. It offers only what
  *  the person's app listener serves. The owner-daemon namespaces (`nodes`, `crons`, …) are absent from its
- *  type and throw `CrouterError` if reached anyway; `files` is `download` only, `profiles` is `list` only, `customObjects` is
+ *  type and throw `CrouterError` if reached anyway; `files` is `download` and `link` only, `profiles` is `list` only, `customObjects` is
  *  `register`, `publish` and `unregister`, and `canvas` is `watch` and `unwatch`.
  *  `request` still sends any route. */
 export class ConnectedCrouter extends AppCrouter {
@@ -88,7 +88,7 @@ export class ConnectedCrouter extends AppCrouter {
                 } });
         }
         const { files, profiles } = this;
-        Object.defineProperty(this, 'files', { value: { download: files.download.bind(files) } });
+        Object.defineProperty(this, 'files', { value: { download: files.download.bind(files), link: files.link.bind(files) } });
         Object.defineProperty(this, 'profiles', { value: { list: profiles.list } });
         const { customObjects, canvas } = this;
         Object.defineProperty(this, 'customObjects', { value: { register: customObjects.register.bind(customObjects), publish: customObjects.publish.bind(customObjects), unregister: customObjects.unregister.bind(customObjects) } });

package/dist/resources/files.d.ts

@@ -10,6 +10,15 @@ export interface FileDownloadOptions {
 }
 /** Opens a raw download; the client supplies the bearer token and refresh. */
 export type FileDownloadOpener = (path: string, options: FileDownloadOptions) => Promise<Response>;
+/** A short-lived signed download link for a file an agent handed over with `crtr push file`. */
+export interface FileLink {
+    /** Fetch this URL (no credentials needed) before `expires_at`. */
+    url: string;
+    expires_at: string;
+    name: string;
+    media_type: string;
+    size: number;
+}
 export declare class Files {
     private readonly request;
     private readonly openDownload?;
@@ -24,11 +33,17 @@ export declare class Files {
         limit?: number;
     } & RequestOptions): Promise<FileListDTO>;
     /**
-     * The raw bytes of a file the caller may read (app listener only). Answers the `Response`
+     * The raw bytes of a file the caller may read, by path (app listener only; refused on a cloud role). Answers the `Response`
      * itself (200, or 206 for `range`) with `Content-Type`, `Content-Length`, and `Content-Range`,
      * so its body can be piped on. A non-2xx answer is thrown as `APIError` — a bad range is
      * 416 `invalid_request` with `param: 'range'` — and never returned as bytes. A body cut
      * short mid-stream means the file could not be read to the end.
      */
     download(path: string, options?: FileDownloadOptions): Promise<Response>;
+    /**
+     * A signed download link for a file an agent handed over (`crtr push file`, announced by a `file.sent` run event), by its `file_id`
+     * (app listener only). The link is short-lived; call again for a new one. A file of another app, another person, or a run the app may
+     * not read is `not_found`.
+     */
+    link(fileId: string, options?: RequestOptions): Promise<FileLink>;
 }

package/dist/resources/files.js

@@ -1,4 +1,5 @@
 import { routes, } from '@north-light/api';
+import { pathSegment } from './identifiers.js';
 import { withQuery } from './request.js';
 export class Files {
     request;
@@ -20,7 +21,7 @@ export class Files {
         return this.request('GET', withQuery(routes.fileList(), { path, limit }), undefined, requestOptions);
     }
     /**
-     * The raw bytes of a file the caller may read (app listener only). Answers the `Response`
+     * The raw bytes of a file the caller may read, by path (app listener only; refused on a cloud role). Answers the `Response`
      * itself (200, or 206 for `range`) with `Content-Type`, `Content-Length`, and `Content-Range`,
      * so its body can be piped on. A non-2xx answer is thrown as `APIError` — a bad range is
      * 416 `invalid_request` with `param: 'range'` — and never returned as bytes. A body cut
@@ -31,4 +32,12 @@ export class Files {
             throw new TypeError('files.download requires a Crouter client');
         return this.openDownload(path, options);
     }
+    /**
+     * A signed download link for a file an agent handed over (`crtr push file`, announced by a `file.sent` run event), by its `file_id`
+     * (app listener only). The link is short-lived; call again for a new one. A file of another app, another person, or a run the app may
+     * not read is `not_found`.
+     */
+    link(fileId, options) {
+        return this.request('GET', `/v1/files/${encodeURIComponent(pathSegment(fileId, 'file id'))}/link`, undefined, options);
+    }
 }

package/dist/resources/shares.d.ts

@@ -1,9 +1,11 @@
 import type { RequestOptions } from '../types.js';
 import type { Request } from './request.js';
-/** `shares.create` input. */
+/** `shares.create` input: exactly one of `path` or `file_id`; none or both is a 400. */
 export interface ShareCreateParams {
-    /** Absolute path of a file the caller may read. Without `crtr:files:share`, only files in the caller's own app space. */
-    path: string;
+    /** Absolute path of a file the caller may read (refused on a cloud role). Without `crtr:files:share`, only files in the caller's own app space. */
+    path?: string;
+    /** The `file_id` of a file an agent handed over with `crtr push file` (from its `file.sent` run event). */
+    file_id?: string;
     /** ISO 8601 time in the future; absent or null keeps the share until it is deleted. */
     expires_at?: string | null;
 }
@@ -17,6 +19,7 @@ export interface ShareCreated {
 export interface Share {
     share_id: string;
     url: string;
+    /** The shared file's name. */
     source_path: string;
     created_by: string;
     created_at: string;

package/dist/skill/northlight/SKILL.md

@@ -2,7 +2,7 @@
 name: northlight
 description: "Use when building, debugging or shipping an app that signs people in with Northlight, starts runs on their Northlight runtime, or calls Northlight providers (sms, search, integrations, context, device) with @north-light/sdk."
 metadata:
-  sdk-version: "0.3.658"
+  sdk-version: "0.3.660"
 ---
 
 # Building a Northlight app
@@ -27,7 +27,7 @@ Never text a person first: Comms refuses a send to anyone who has not texted you
 
 ## First: check this skill matches the SDK
 
-This skill is for SDK version `0.3.658`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. It needs no account. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
+This skill is for SDK version `0.3.660`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. It needs no account. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
 
 ## Where things run
 

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export declare const SDK_VERSION = "0.3.658";
+export declare const SDK_VERSION = "0.3.660";
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the
  *  contract level existed (which only knows this header) refuses this SDK, while every later runtime accepts it. */
 export declare const LEGACY_FLOOR = "0.3.423";

package/dist/version.js

@@ -1,6 +1,6 @@
 // SDK_VERSION is written by scripts/release-version.mjs on every release; do not edit by hand.
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export const SDK_VERSION = '0.3.658';
+export const SDK_VERSION = '0.3.660';
 // LEGACY_FLOOR is written once by `scripts/contract.mjs release`, at the first release that carries the contract level
 // (the `0.0.0` placeholder is replaced there and never again); do not edit by hand.
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@north-light/sdk",
-  "version": "0.3.658",
-  "crouterContract": "1.52",
+  "version": "0.3.660",
+  "crouterContract": "1.53",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,9 +44,9 @@
     "prepublishOnly": "node -e \"if (process.env.npm_config_tag !== 'next') { console.error('@north-light/sdk publishes only with --tag next; scripts/promote-sdk.mjs is the only mover of latest.'); process.exit(1); }\""
   },
   "dependencies": {
-    "@north-light/api": "0.3.658",
-    "@north-light/identity": "0.3.658",
-    "@north-light/plugin": "0.3.658",
+    "@north-light/api": "0.3.660",
+    "@north-light/identity": "0.3.660",
+    "@north-light/plugin": "0.3.660",
     "jose": "^6.2.1"
   },
   "peerDependencies": {