@t4h.framework/sftp 0.8.6 → 0.9.2

package/.ai/skills/framework-sftp/SKILL.md

@@ -1,152 +1,25 @@
 ---
 name: framework-sftp
 description: >-
-  Guides correct use of @t4h.framework/sftp in T4H Framework workflows: SFTP
-  activities, SftpClaim runtime dependency, the reconciler-aware Sftp client,
-  Binary file payloads, and testing with TestWorkflowEnvironment. Use when
-  implementing SFTP upload/download/list in workflows, wiring SftpClaim providers,
-  mocking SftpClaim in workflow tests, working in packages/sftp, or integrating
-  remote file transfer (sftp:// connection strings, put/get, mkdir, stat, exists).
+  Guides the use of @t4h.framework/sftp to read and write files on an SFTP
+  server from a T4H Framework workflow: the Sftp client (get, put, append,
+  list, exists, stat, mkdir, rmdir, rename, copy, delete, chmod, downloadDir),
+  sftp:// connection strings as a Secret, the Binary returned by get and its
+  SftpBinary slice, and how to test with TestWorkflowEnvironment and mockClaim
+  of SftpClaim. Use when a workflow must download, upload, list, move or
+  delete remote files, or when someone asks for ssh2, ssh2-sftp-client or an
+  SFTP connection in a workflow.
 ---
 
 # @t4h.framework/sftp
 
-SFTP **activities**, **`SftpClaim`**, and a high-level **`Sftp`** client for replayable remote file operations in workflows. Package path: `framework/packages/sftp`. Peer dependency: `@t4h.framework/core` (`Binary`, `SyncActivity`, `Claim`, `History`).
+## Use the client
 
-Import surface (the package entry; its `exports` map has only `.`, so `tsc` rejects a deep import):
-
-```typescript
-import {
-  Sftp,
-  SftpClaim,
-  SftpAppendActivity,
-  SftpChmodActivity,
-  SftpCopyActivity,
-  SftpCwdActivity,
-  SftpDeleteActivity,
-  SftpDownloadDirActivity,
-  SftpExistsActivity,
-  SftpGetActivity,
-  SftpListActivity,
-  SftpMkdirActivity,
-  SftpPutActivity,
-  SftpRealPathActivity,
-  SftpRenameActivity,
-  SftpRmdirActivity,
-  SftpStatActivity,
-  type SftpAppendActivityInput,
-  type SftpChmodActivityInput,
-  type SftpCopyActivityInput,
-  type SftpCwdActivityInput,
-  type SftpDeleteActivityInput,
-  type SftpDownloadDirActivityInput,
-  type SftpExistsActivityInput,
-  type SftpExistsResult,
-  type SftpGetActivityInput,
-  type SftpFileInfo,
-  type SftpListActivityInput,
-  type SftpMkdirActivityInput,
-  type SftpPutActivityInput,
-  type SftpRealPathActivityInput,
-  type SftpRenameActivityInput,
-  type SftpRmdirActivityInput,
-  type SftpStatActivityInput,
-  type SftpStat,
-} from '@t4h.framework/sftp'
-
-import type { Binary } from '@t4h.framework/core'
-```
-
-Node `>=22`. See [README.md](../../../README.md).
-
----
-
-## Architecture
-
-`Workflow` → **`Sftp`** (`History.bind` per activity) → shipped `Sftp*Activity` → **`SftpClaim.<method>(input)`** (runtime impl).
-
-From a workflow you call the **`Sftp`** client; it forwards each method to the
-bound, replay-safe activity for you. The claim method name matches the client
-method (`get`, `put`, `delete`, …) and the runtime supplies the `SftpClaim`
-implementation.
-
----
-
-## Claims
-
-### SftpClaim (required)
-
-Runtime must register a concrete implementation:
-
-```typescript
-{ provide: SftpClaim, value: new MySftpClaimImpl() }
-```
-
-Abstract contract (each method accepts the corresponding `*ActivityInput` type):
-
-| Method | Input type | Return |
-|--------|------------|--------|
-| `append` | `SftpAppendActivityInput` | `void` |
-| `chmod` | `SftpChmodActivityInput` | `void` |
-| `copy` | `SftpCopyActivityInput` | `void` |
-| `cwd` | `SftpCwdActivityInput` | `string` |
-| `delete` | `SftpDeleteActivityInput` | `void` |
-| `downloadDir` | `SftpDownloadDirActivityInput` | `Binary` |
-| `exists` | `SftpExistsActivityInput` | `SftpExistsResult` |
-| `get` | `SftpGetActivityInput` | `Binary` |
-| `list` | `SftpListActivityInput` | `SftpFileInfo[]` |
-| `mkdir` | `SftpMkdirActivityInput` | `void` |
-| `put` | `SftpPutActivityInput` | `void` |
-| `realPath` | `SftpRealPathActivityInput` | `string` |
-| `rename` | `SftpRenameActivityInput` | `void` |
-| `rmdir` | `SftpRmdirActivityInput` | `void` |
-| `stat` | `SftpStatActivityInput` | `SftpStat` |
-
-Methods may return sync values or `Promise`s.
-
----
-
-## Sftp client (preferred in workflows)
-
-Instantiate with the `EnvDesign` entry declared `type: Secret` (the constructor takes a `Secret`, so a string is a `tsc` error). The URL `sftp://user:pass@host:22` carries the password; the host reads the value where each activity runs:
-
-```typescript
-import { Sftp } from '@t4h.framework/sftp'
-
-import { environments } from '../constants/environments.js'
-
-const sftp = new Sftp(environments.SFTP_URL) // Secret
-```
-
-### Methods
-
-| Method | Args | Returns |
-|--------|------|---------|
-| `append` | `filepath`, `content: Binary` | `void` |
-| `chmod` | `path`, `mode: string \| number` | `void` |
-| `copy` | `srcPath`, `destPath` | `void` |
-| `cwd` | — | `string` |
-| `delete` | `path`, `noErrorOK?: boolean` | `void` |
-| `downloadDir` | `path` | `Binary` |
-| `exists` | `path` | `SftpExistsResult` |
-| `get` | `filepath` | `Binary` |
-| `list` | `path` | `SftpFileInfo[]` |
-| `mkdir` | `path`, `recursive?: boolean` | `void` |
-| `put` | `filepath`, `content: Binary` | `void` |
-| `realPath` | `path` | `string` |
-| `rename` | `srcPath`, `destPath` | `void` |
-| `rmdir` | `path`, `recursive?: boolean` | `void` |
-| `stat` | `path` | `SftpStat` |
-
-**Flags:**
-
-- **`delete(path, true)`** — `noErrorOK`: suppress error when file missing.
-- **`mkdir(path, true)`** — `recursive`: create intermediate directories.
-- **`rmdir(path, true)`** — `recursive`: remove directory tree.
-
-**`exists`:** `false` if not found; otherwise `'d'` (directory), `'-'` (file), `'l'` (symlink).
-
-### Example workflow usage
+1. Declare the connection string as a `Secret` in the `EnvDesign` in
+   `src/constants/environments.ts`. The URL (`sftp://user:pass@host:22`)
+   carries the password.
+2. Create one `Sftp` client and call its methods in the workflow body. Each
+   call is one durable step.
 
 ```typescript
 // src/constants/environments.ts
@@ -158,170 +31,71 @@ export const environments = EnvDesign({
 ```
 
 ```typescript
-import { Workflow } from '@t4h.framework/core'
 import { Sftp } from '@t4h.framework/sftp'
 
 import { environments } from '../constants/environments.js'
 
 const sftp = new Sftp(environments.SFTP_URL)
 
-export const ingestRemoteFile = new Workflow({ id: 'ingest-remote-file' }, async () => {
-  const remotePath = '/incoming/report.csv'
-
-  if ((await sftp.exists(remotePath)) === false) {
-    return { ok: false, reason: 'missing' }
-  }
+for (const entry of await sftp.list('/inbound')) {
+  if (entry.type !== '-') continue
 
-  const file = await sftp.get(remotePath)
-  await sftp.rename(remotePath, '/processed/report.csv')
-
-  return { ok: true, size: file /* use Binary APIs from core */ }
-})
-```
-
----
-
-## Using SFTP in a workflow via `History.reconciler`
-
-Prefer the **`Sftp`** client. When you need the exported activity directly,
-drive the **shipped** `Sftp*Activity` class through `History.reconciler` — this
-is a ready, replay-safe helper.
-`@t4h.framework/core/no-framework-activity-in-app` rejects `new` and `extends`
-on these classes; pass them as they are.
-
-```typescript
-import { History } from '@t4h.framework/core'
-import { Sftp, SftpGetActivity } from '@t4h.framework/sftp'
-
-const sftp = new Sftp(environments.SFTP_URL) // Secret
-const content = await History.reconciler(SftpGetActivity, sftp, '/remote/file.txt')
-```
-
-Activity ↔ client mapping:
-
-| Activity | Client method |
-|----------|---------------|
-| `SftpAppendActivity` | `append` |
-| `SftpChmodActivity` | `chmod` |
-| `SftpCopyActivity` | `copy` |
-| `SftpCwdActivity` | `cwd` |
-| `SftpDeleteActivity` | `delete` |
-| `SftpDownloadDirActivity` | `downloadDir` |
-| `SftpExistsActivity` | `exists` |
-| `SftpGetActivity` | `get` |
-| `SftpListActivity` | `list` |
-| `SftpMkdirActivity` | `mkdir` |
-| `SftpPutActivity` | `put` |
-| `SftpRealPathActivity` | `realPath` |
-| `SftpRenameActivity` | `rename` |
-| `SftpRmdirActivity` | `rmdir` |
-| `SftpStatActivity` | `stat` |
-
----
-
-## Activity input shapes
-
-All inputs include **`connectionString: Secret`** (the name of the env entry; the value is read on the host). Path field names differ by operation:
-
-| Input type | Fields (beyond `connectionString`) |
-|------------|-----------------------------------|
-| `SftpAppendActivityInput` | `filepath`, `content: Binary` |
-| `SftpChmodActivityInput` | `path`, `mode: string \| number` |
-| `SftpCopyActivityInput` | `srcPath`, `destPath` |
-| `SftpCwdActivityInput` | _(none)_ |
-| `SftpDeleteActivityInput` | `path`, `noErrorOK?: boolean` |
-| `SftpDownloadDirActivityInput` | `path` |
-| `SftpExistsActivityInput` | `path` |
-| `SftpGetActivityInput` | `filepath` |
-| `SftpListActivityInput` | `path` |
-| `SftpMkdirActivityInput` | `path`, `recursive?: boolean` |
-| `SftpPutActivityInput` | `filepath`, `content: Binary` |
-| `SftpRealPathActivityInput` | `path` |
-| `SftpRenameActivityInput` | `srcPath`, `destPath` |
-| `SftpRmdirActivityInput` | `path`, `recursive?: boolean` |
-| `SftpStatActivityInput` | `path` |
-
----
-
-## Result types
-
-### `SftpExistsResult`
-
-```typescript
-type SftpExistsResult = false | 'd' | '-' | 'l'
-```
-
-### `SftpFileInfo` (`list`)
-
-```typescript
-type SftpFileInfo = {
-  name: string
-  type: 'd' | '-' | 'l'
-  size: number
-  modifyTime: number
-  accessTime: number
-  rights: { user: string; group: string; other: string }
-  owner: number
-  group: number
-  longname: string
+  const file = await sftp.get(`/inbound/${entry.name}`)
+  await sftp.put(`/archive/${entry.name}`, file)
+  await sftp.delete(`/inbound/${entry.name}`, true)
 }
 ```
 
-### `SftpStat` (`stat`)
-
-```typescript
-type SftpStat = {
-  mode: number
-  uid: number
-  gid: number
-  size: number
-  accessTime: number
-  modifyTime: number
-  isDirectory: boolean
-  isFile: boolean
-  isBlockDevice: boolean
-  isCharacterDevice: boolean
-  isSymbolicLink: boolean
-  isFIFO: boolean
-  isSocket: boolean
-}
-```
-
----
-
-## Testing
-
-Test the **workflow** with `TestWorkflowEnvironment` from
-`@t4h.framework/core/testing`, mocking `SftpClaim` — the single claim every
-`Sftp*Activity` resolves. Provide only the methods your workflow triggers
-(`get`, `put`, `delete`, …). See the **framework-workflow-testing** skill for the
-harness API.
+## Traps
+
+- `new Sftp(...)` takes a `Secret`. A string literal or a `String` env entry is
+  a type error.
+- `get` returns a `Binary`, a reference to the remote file. Pass it to the
+  next step (`put`, `split`, `unzip`). Do not buffer it in the workflow. To
+  read a header or a trailer, use `read` from `@t4h.framework/fs` with a
+  `range`; see the `framework-fs` skill.
+- `put` and `append` take a `Binary`, not a string or a `Buffer`. Make one with
+  `write` from `@t4h.framework/fs`. Never build a `Binary` by hand.
+- `exists` returns `false` or a type character (`'d'`, `'-'`, `'l'`), not a
+  boolean. `if (await sftp.exists(p))` works; `=== true` never matches.
+- The boolean second arguments are positional: `delete(path, true)` gives no
+  error when the file is missing, `mkdir(path, true)` and `rmdir(path, true)`
+  are recursive.
+- `SftpBinary.slice(range)`: `range` is relative to the binary you slice, `end`
+  is exclusive, and it throws a `RangeError` outside the binary.
+- `@t4h.framework/core/no-io-in-workflow` rejects `ssh2`, `ssh2-sftp-client`
+  and `basic-ftp` in a workflow. Use `Sftp`.
+- Do not `new` or `extend` an `Sftp*Activity`
+  (`@t4h.framework/core/no-framework-activity-in-app`). Use the client.
+- The runtime must provide `SftpClaim`.
+
+## Test
+
+Mock `SftpClaim` with only the methods the workflow calls. Each claim method
+has the name of the client method and receives an input object with
+`connectionString` and the call arguments. The path field is `filepath` for
+`get`, `put` and `append`, `srcPath` and `destPath` for `copy` and `rename`,
+and `path` for the others.
 
 ```typescript
 import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
 import { SftpClaim } from '@t4h.framework/sftp'
 
-const mockGet = vi.fn().mockImplementation(async () => someBinary)
+const get = vi.fn().mockResolvedValue(binary)
 
 const env = TestWorkflowEnvironment.create({ now: 0 })
 
-const output = await env.execute(workflow, input, {
-  claims: [mockClaim(SftpClaim, { get: mockGet })],
+await env.execute(workflow, input, {
+  claims: [mockClaim(SftpClaim, { get, put: vi.fn() })],
+  env: { SFTP_URL: 'sftp://user:pass@sftp.example.com:22' },
 })
 
-// each SftpClaim method receives the activity's serializable input
-expect(mockGet.mock.calls[0][0]).toMatchObject({ filepath: '/remote/file.txt' })
+expect(get.mock.calls[0][0]).toMatchObject({ filepath: '/inbound/a.csv' })
 ```
 
----
-
-## Checklist for agents
-
-1. Prefer **`new Sftp(connectionString)`** in workflow code — not raw SSH/SFTP libraries.
-2. Never perform non-replayable SFTP I/O inside workflows — use **`Sftp`** or **`History.reconciler(Sftp*Activity, ...)`**.
-3. Ensure runtime provides **`SftpClaim`** (or pass a mock in tests).
-4. Use **`exists`** before destructive ops when idempotency matters; use **`delete(..., true)`** for tolerant deletes.
-5. Use **`mkdir(..., true)`** / **`rmdir(..., true)`** only when recursive tree ops are intended.
-6. Test workflows with **`TestWorkflowEnvironment`** + **`mockClaim(SftpClaim, ...)`**; assert on the mock's `mock.calls`.
+## Reference
 
-See also: `packages/sftp/README.md`; **framework-workflow-testing** for the test harness.
+- Guide: https://tech4humans-brasil.github.io/framework/sftp/
+- Secrets: https://tech4humans-brasil.github.io/framework/core/environment
+- Workflow testing: https://tech4humans-brasil.github.io/framework/core/testing
+- Types: `node_modules/@t4h.framework/sftp/dist/sftp.d.ts`

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @t4h.framework/sftp
 
+## 0.9.2
+
+### Patch Changes
+
+- [#276](https://github.com/tech4humans-brasil/framework/pull/276) [`7b38934`](https://github.com/tech4humans-brasil/framework/commit/7b38934e8f9207c98c33afcd76e3a7a4da7e8b14) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The docs tell that `get` returns a `Binary`, and show how to make the `Binary` of a test with `SftpBinary.from`.
+
+## 0.9.1
+
+## 0.9.0
+
+### Minor Changes
+
+- [#246](https://github.com/tech4humans-brasil/framework/pull/246) [`b99b41f`](https://github.com/tech4humans-brasil/framework/commit/b99b41f60d69b3037187e9fcdc27ab0d47ff18a2) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Adds byte windows to `SftpBinary`. `binary.slice(range)` returns a view of a byte window of the remote file that reuses the stream of `binary`. The new `range` field is absolute in the file, with an exclusive `end`, and `contentLength` is `range.end - range.start`. A slice of a slice composes. `toJSON()` includes `range` on a slice only, so the JSON of a whole file does not change. `slice` throws a `RangeError` when the window is not inside the binary. In `@t4h.framework/fs`, the docs no longer give an SFTP reference as an example of a binary that cannot be sliced.
+
+### Patch Changes
+
+- [#257](https://github.com/tech4humans-brasil/framework/pull/257) [`586bfb4`](https://github.com/tech4humans-brasil/framework/commit/586bfb4663f4a478527ee0c8db360603f034d615) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The sftp README is now short and links to the site. The docs page now has the testing, slice and runtime sections, and the skill keeps only the traps that the types do not show.
+
 ## 0.8.6
 
 ### Patch Changes

package/README.md

@@ -1,25 +1,20 @@
 # @t4h.framework/sftp
 
-SFTP activities, claim, and a high-level client for file operations within workflows.
+Reads and writes files on an SFTP server from a T4H Framework workflow. Each
+operation (`get`, `put`, `list`, `rename` and more) is a durable step.
 
-## Claim
+## Install
 
-### SftpClaim
-
-Single abstract dependency that backs all SFTP activities. The runtime must provide a concrete implementation.
-
-```typescript
-import { SftpClaim } from '@t4h.framework/sftp'
-
-// the runtime provides this:
-// { provide: SftpClaim, value: new MySftpClaimImpl() }
+```bash
+npm install @t4h.framework/sftp
 ```
 
-## Sftp
+Peer dependency: `@t4h.framework/core`.
 
-High-level SFTP client that wraps every activity behind a simple API. Instantiated with a connection string.
+## Usage
 
-The connection string `sftp://user:pass@host:22` carries the password, so the constructor takes a `Secret` and `tsc` rejects a string. Declare it with `type: Secret` in the `EnvDesign` in `src/constants/environments.ts`:
+The connection string carries the password, so declare it with
+`type: Secret` in the `EnvDesign` in `src/constants/environments.ts`:
 
 ```typescript
 // src/constants/environments.ts
@@ -31,168 +26,21 @@ export const environments = EnvDesign({
 ```
 
 ```typescript
+import { Workflow } from '@t4h.framework/core'
 import { Sftp } from '@t4h.framework/sftp'
 
 import { environments } from './constants/environments.js'
 
 const sftp = new Sftp(environments.SFTP_URL)
-```
-
-### append
-
-Appends content to an existing remote file.
-
-```typescript
-await sftp.append('/remote/path/file.txt', myBinaryContent) // void
-```
-
-### chmod
-
-Changes the permissions of a remote file or directory.
-
-```typescript
-await sftp.chmod('/remote/path/file.txt', 0o755) // void
-```
-
-### copy
-
-Copies a remote file from one path to another.
-
-```typescript
-await sftp.copy('/remote/src.txt', '/remote/dest.txt') // void
-```
-
-### cwd
-
-Returns the current working directory on the remote server.
-
-```typescript
-const dir = await sftp.cwd() // string
-```
-
-### delete
-
-Deletes a remote file. Pass `true` as the second argument to suppress errors when the file does not exist.
-
-```typescript
-await sftp.delete('/remote/path/file.txt') // void
-await sftp.delete('/remote/path/file.txt', true) // void, no error if missing
-```
-
-### downloadDir
-
-Downloads a remote directory as binary content.
-
-```typescript
-const content = await sftp.downloadDir('/remote/path') // Binary
-```
-
-### exists
-
-Checks whether a remote path exists. Returns `false` if not found, or its type character (`'d'` directory, `'-'` file, `'l'` symlink).
-
-```typescript
-const result = await sftp.exists('/remote/path') // false | 'd' | '-' | 'l'
-```
-
-### get
-
-Downloads a single remote file.
 
-```typescript
-const content = await sftp.get('/remote/path/file.txt') // Binary
-```
-
-### list
-
-Lists the contents of a remote directory.
-
-```typescript
-const files = await sftp.list('/remote/path') // SftpFileInfo[]
-```
-
-`SftpFileInfo`:
-
-```typescript
-type SftpFileInfo = {
-  name: string
-  type: 'd' | '-' | 'l'
-  size: number
-  modifyTime: number
-  accessTime: number
-  rights: { user: string; group: string; other: string }
-  owner: number
-  group: number
-  longname: string
-}
-```
-
-### mkdir
-
-Creates a remote directory. Pass `true` as the second argument to create intermediate directories recursively.
-
-```typescript
-await sftp.mkdir('/remote/path/new-dir') // void
-await sftp.mkdir('/remote/path/a/b/c', true) // void, recursive
-```
-
-### put
-
-Uploads content to a remote file.
-
-```typescript
-await sftp.put('/remote/path/file.txt', myBinaryContent) // void
-```
+const ingest = new Workflow({ id: 'ingest' }, async () => {
+  const file = await sftp.get('/inbound/orders.csv')
 
-### realPath
-
-Resolves the absolute path of a remote path (expanding symlinks, `.`, `..`, etc.).
-
-```typescript
-const abs = await sftp.realPath('/remote/./path/../file.txt') // string
-```
-
-### rename
-
-Renames (moves) a remote file or directory.
-
-```typescript
-await sftp.rename('/remote/old-name.txt', '/remote/new-name.txt') // void
-```
-
-### rmdir
-
-Removes a remote directory. Pass `true` as the second argument to remove recursively.
-
-```typescript
-await sftp.rmdir('/remote/path/empty-dir') // void
-await sftp.rmdir('/remote/path/full-dir', true) // void, recursive
-```
-
-### stat
-
-Returns detailed metadata about a remote path.
-
-```typescript
-const info = await sftp.stat('/remote/path/file.txt') // SftpStat
+  await sftp.put('/archive/orders.csv', file)
+  await sftp.delete('/inbound/orders.csv')
+})
 ```
 
-`SftpStat`:
+## Documentation
 
-```typescript
-type SftpStat = {
-  mode: number
-  uid: number
-  gid: number
-  size: number
-  accessTime: number
-  modifyTime: number
-  isDirectory: boolean
-  isFile: boolean
-  isBlockDevice: boolean
-  isCharacterDevice: boolean
-  isSymbolicLink: boolean
-  isFIFO: boolean
-  isSocket: boolean
-}
-```
+https://tech4humans-brasil.github.io/framework/sftp/

package/dist/models/SftpBinary.d.ts

@@ -1,6 +1,6 @@
 import type { Readable } from 'node:stream';
 import { Binary, type Secret } from '@t4h.framework/core';
-interface SftpBinaryJSON {
+export interface SftpBinaryJSON {
     filepath: string;
     contentType: string;
     contentLength: number;
@@ -11,16 +11,26 @@ export declare class SftpBinary extends Binary {
     readonly contentType: string;
     readonly contentLength: number;
     readonly stream: (this: SftpBinary) => Readable | Promise<Readable>;
-    protected constructor(connectionString: Secret, filepath: string, contentType: string, contentLength: number, stream: (this: SftpBinary) => Readable | Promise<Readable>);
+    readonly range?: {
+        start: number;
+        end: number;
+    } | undefined;
+    protected constructor(connectionString: Secret, filepath: string, contentType: string, contentLength: number, stream: (this: SftpBinary) => Readable | Promise<Readable>, range?: {
+        start: number;
+        end: number;
+    } | undefined);
     static from(connectionString: Secret, file: SftpBinaryJSON, stream: (self: SftpBinary) => Readable | Promise<Readable>): SftpBinary;
+    slice(range: {
+        start: number;
+        end: number;
+    }): SftpBinary;
     toJSON(): {
         connectionString: Secret;
-        file: {
-            filepath: string;
-            contentType: string;
-            contentLength: number;
+        file: SftpBinaryJSON;
+        range?: {
+            start: number;
+            end: number;
         };
     };
 }
-export {};
 //# sourceMappingURL=SftpBinary.d.ts.map

package/dist/models/SftpBinary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SftpBinary.d.ts","sourceRoot":"","sources":["../../src/models/SftpBinary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAEzD,UAAU,cAAc;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,qBAAa,UAAW,SAAQ,MAAM;aAElB,gBAAgB,EAAE,MAAM;aACxB,QAAQ,EAAE,MAAM;aAChB,WAAW,EAAE,MAAM;aACnB,aAAa,EAAE,MAAM;aACrB,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAL5E,SAAS,aACS,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;WAK9D,IAAI,CAChB,gBAAgB,EAAE,MAAM,EACxB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAarD,MAAM;;;;;;;;CAUd"}
+{"version":3,"file":"SftpBinary.d.ts","sourceRoot":"","sources":["../../src/models/SftpBinary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAEzD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,qBAAa,UAAW,SAAQ,MAAM;aAElB,gBAAgB,EAAE,MAAM;aACxB,QAAQ,EAAE,MAAM;aAChB,WAAW,EAAE,MAAM;aACnB,aAAa,EAAE,MAAM;aACrB,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;aAC1D,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;IANxD,SAAS,aACS,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,EAC1D,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,YAAA;WAK1C,IAAI,CAChB,gBAAgB,EAAE,MAAM,EACxB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAarD,KAAK,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU;IAmBxD,MAAM,IAAI;QACf,gBAAgB,EAAE,MAAM,CAAA;QACxB,IAAI,EAAE,cAAc,CAAA;QACpB,KAAK,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;KACvC;CAcF"}

package/dist/models/SftpBinary.js

@@ -5,21 +5,31 @@ export class SftpBinary extends Binary {
     contentType;
     contentLength;
     stream;
-    constructor(connectionString, filepath, contentType, contentLength, stream) {
+    range;
+    constructor(connectionString, filepath, contentType, contentLength, stream, range) {
         super();
         this.connectionString = connectionString;
         this.filepath = filepath;
         this.contentType = contentType;
         this.contentLength = contentLength;
         this.stream = stream;
+        this.range = range;
     }
     static from(connectionString, file, stream) {
         return new this(connectionString, file.filepath, file.contentType, file.contentLength, function () {
             return stream(this);
         });
     }
+    slice(range) {
+        if (range.start < 0 || range.end < range.start)
+            throw new RangeError('Slice range must be a non-negative byte window');
+        if (range.end > this.contentLength)
+            throw new RangeError('Slice range must not exceed the binary length');
+        const base = this.range?.start ?? 0;
+        return new SftpBinary(this.connectionString, this.filepath, this.contentType, range.end - range.start, this.stream, { start: base + range.start, end: base + range.end });
+    }
     toJSON() {
-        return {
+        const json = {
             connectionString: this.connectionString,
             file: {
                 filepath: this.filepath,
@@ -27,6 +37,9 @@ export class SftpBinary extends Binary {
                 contentLength: this.contentLength,
             },
         };
+        if (!this.range)
+            return json;
+        return { ...json, range: { ...this.range } };
     }
 }
 //# sourceMappingURL=SftpBinary.js.map

package/dist/models/SftpBinary.js.map

@@ -1 +1 @@
-{"version":3,"file":"SftpBinary.js","sourceRoot":"","sources":["../../src/models/SftpBinary.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAe,MAAM,qBAAqB,CAAA;AAQzD,MAAM,OAAO,UAAW,SAAQ,MAAM;IAElB;IACA;IACA;IACA;IACA;IALlB,YACkB,gBAAwB,EACxB,QAAgB,EAChB,WAAmB,EACnB,aAAqB,EACrB,MAA0D;QAE1E,KAAK,EAAE,CAAA;QANS,qBAAgB,GAAhB,gBAAgB,CAAQ;QACxB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,gBAAW,GAAX,WAAW,CAAQ;QACnB,kBAAa,GAAb,aAAa,CAAQ;QACrB,WAAM,GAAN,MAAM,CAAoD;IAG5E,CAAC;IAEM,MAAM,CAAC,IAAI,CAChB,gBAAwB,EACxB,IAAoB,EACpB,MAA0D;QAE1D,OAAO,IAAI,IAAI,CACb,gBAAgB,EAChB,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,aAAa,EAClB;YACE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAA;QACrB,CAAC,CACF,CAAA;IACH,CAAC;IAEM,MAAM;QACX,OAAO;YACL,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,IAAI,EAAE;gBACJ,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,aAAa,EAAE,IAAI,CAAC,aAAa;aAClC;SACF,CAAA;IACH,CAAC;CACF"}
+{"version":3,"file":"SftpBinary.js","sourceRoot":"","sources":["../../src/models/SftpBinary.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAe,MAAM,qBAAqB,CAAA;AAQzD,MAAM,OAAO,UAAW,SAAQ,MAAM;IAElB;IACA;IACA;IACA;IACA;IACA;IANlB,YACkB,gBAAwB,EACxB,QAAgB,EAChB,WAAmB,EACnB,aAAqB,EACrB,MAA0D,EAC1D,KAAsC;QAEtD,KAAK,EAAE,CAAA;QAPS,qBAAgB,GAAhB,gBAAgB,CAAQ;QACxB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,gBAAW,GAAX,WAAW,CAAQ;QACnB,kBAAa,GAAb,aAAa,CAAQ;QACrB,WAAM,GAAN,MAAM,CAAoD;QAC1D,UAAK,GAAL,KAAK,CAAiC;IAGxD,CAAC;IAEM,MAAM,CAAC,IAAI,CAChB,gBAAwB,EACxB,IAAoB,EACpB,MAA0D;QAE1D,OAAO,IAAI,IAAI,CACb,gBAAgB,EAChB,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,aAAa,EAClB;YACE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAA;QACrB,CAAC,CACF,CAAA;IACH,CAAC;IAEM,KAAK,CAAC,KAAqC;QAChD,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,KAAK;YAC5C,MAAM,IAAI,UAAU,CAAC,gDAAgD,CAAC,CAAA;QAExE,IAAI,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,aAAa;YAChC,MAAM,IAAI,UAAU,CAAC,+CAA+C,CAAC,CAAA;QAEvE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,EAAE,KAAK,IAAI,CAAC,CAAA;QAEnC,OAAO,IAAI,UAAU,CACnB,IAAI,CAAC,gBAAgB,EACrB,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,WAAW,EAChB,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,KAAK,EACvB,IAAI,CAAC,MAAM,EACX,EAAE,KAAK,EAAE,IAAI,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,CACrD,CAAA;IACH,CAAC;IAEM,MAAM;QAKX,MAAM,IAAI,GAAG;YACX,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,IAAI,EAAE;gBACJ,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,aAAa,EAAE,IAAI,CAAC,aAAa;aAClC;SACF,CAAA;QAED,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAA;QAE5B,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,EAAE,CAAA;IAC9C,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/sftp",
-  "version": "0.8.6",
+  "version": "0.9.2",
   "description": "SFTP module for the T4H Framework",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/sftp",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -33,7 +33,7 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.20.0",
+    "@t4h.framework/core": "^0.21.2",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },