Skip to content

v3.0.0

Choose a tag to compare

View all tags
@shawn-tsanet shawn-tsanet released this 21 Oct 01:19
v3.0.0
23b7489
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

connect-library 3.0.0, attachment-receiver 3.0.0

Major version. The V2 attachment client is rebuilt on the grant model in the Connect OpenAPI spec, and its public types change incompatibly. Senders can restrict which companies receive their V2 attachments, and receivers can configure their own storage. Case notes take their types from the server. /v1/ failures now arrive as problem details, and Connect API calls run on the JDK's HTTP client. Runtime unchanged from 2.0.0: Spring Boot 4.1, Jackson 3, JDK 21.

The full upgrade guide, with every removed type, method and error code, is the 3.0.0 entry in skills/connect-sdk-deploy/references/consume-artifact.md.

Breaking changes for consumers

  1. The V2 attachment client is rebuilt from the spec (#96, #100). attachmentsV2() has one method per Connect API call: createGrant, getGrant, listGrants, singleUploadLink, s3PartLinks, azureBlockLinks, the three complete* calls and abandon. It also keeps complete for the grant's mode, upload and a four-argument send that returns the completed AttachmentGrant.

    • Removed: grant, the old upload and complete signatures, the six-argument send, and AttachmentGrantRequest, AttachmentCompleteRequest and AttachmentCompleteResult.
    • AttachmentGrant is now the server's grant: a long id, Status, UploadMode and UploadPlan. It takes no content type, SHA-256 or description, and has no DELIVERED or note-id outcome.
    • AttachmentV2Exception: problemType() and isProblem are replaced by code() and is(code), with codes chosen by HTTP status. Several 2.0.0 codes are removed; the upgrade guide maps each one.
    • send no longer re-grants when a grant expires before complete.

  2. /v1/ failures are problem details (#127, #129). The library now sends Accept: application/json, application/problem+json. A failed /v1/ call now carries the documented 4xx status where 2.0.0 often saw a 500, with type() and title() set, and the message reads HTTP <status> <title> (<type suffix>): <detail>. Code that branches on kind() == LEGACY, on status() or on the message text sees different values: sweep for it. A wrong password is a PROBLEM too.

  3. Connect API calls use java.net.http.HttpClient (#128, #131 to #134), one client per session. The JVM's proxy selector and SSL context still apply.

    • No longer honored: a default Authenticator for an authenticating proxy, and HttpsURLConnection's default socket factory and hostname verifier.
    • Redirects: a redirected GET is no longer followed. Any 3xx is OTHER, and the message never names the Location.
    • Interrupts: an interrupted call stops with OTHER, status 0, and leaves the thread interrupted.

  4. Interface and record changes.

    • TsaNetApiSession gains attachmentStorage().
    • CaseNotesFacade gains listNoteTypes() and a five-argument createNote.
    • ApplicationUserAccount and TsaNetApiConfiguration gain an allowedReceiverCompanyIds component.
    • CaseNoteDto grows from 14 to 18 components.

    Callers are unaffected. Implementers and decorators must add the new methods. A record pattern over a changed record stops compiling. The 2.0.0 constructors still compile, and the CaseNoteDto one is deprecated.

  5. A V2 upload link missing expiresAt or sizeBytes is refused (#138). An upload-link answer without expiresAt (any link), or without sizeBytes (an S3 part or Azure block), fails with AttachmentV2Exception CLIENT_PRECONDITION "the answer has no ...". It used to silently turn off link refresh or the part-size check. The spec requires both fields, and the platform sends them.

New

  • Receiver allowlist, part 1 of #92 (#104). Set it with ApplicationUserAccount.withAllowedReceiverCompanyIds, or with allowed-receiver-company-ids in the console's account config.
    • With a list set: createGrant (and so send) refuses a case whose receiving company isn't on it with attachment/receiver-not-allowed, before any grant is requested. The platform's own allowlist refusal (403) is reported as the same code.
    • Empty or null: unrestricted.
  • Receiver storage (#106, #107). session.attachmentStorage() gets, registers and tests the company's S3 or Azure Blob storage. The demo-ui has a Settings page for it, read-only unless TSANET_DEMO_RECEIVER_STORAGE_EDITABLE is set.
  • Note types from the server (#99, #103, reworked in #124 to #126).
    • Listing types: listNoteTypes() returns the codes a caller may send, from GET /v1/note-types.
    • Creating: createNote(..., type) sends the code as given, and a code the server doesn't offer is a 400 invalid-note-type.
    • No default: a null type creates a note with no type, and nothing becomes partner.
    • Reading notes: they carry type, typeDisplayName, companyId and direction.
    • The SQLite cache adds the four columns at startup.
  • Upload loop on the spec's links.
    • Links: requested just before use, in batches of up to 1,000, and refreshed when they expire within 60 seconds.
    • Retries: bounded per part, honoring Retry-After.
    • Wire: link headers are sent unchanged, S3 ETags are kept for complete, and links never appear in logs or messages.

Unchanged

  • V1 attachments and every other V1 facade signature, apart from the additions above.
  • Runtime line: Spring Boot 4.1, Jackson 3, JDK 21.
  • attachment-receiver: its source is unchanged since 2.0.0. It is published at 3.0.0 because the two modules release together.

Consuming the artifacts

Get com.tsanet:connect-library:3.0.0 and com.tsanet:attachment-receiver:3.0.0 from https://maven.pkg.github.com/tsanetgit/Connect_SDK. A read:packages token is required even for public packages.

Building from source needs a Connect-API-Code spec branch that has the Attachment Grants and Attachment Storage Config operations. beta has them since tsanetgit/Connect-API-Code#208.

The V2 endpoints are x-stability-level: alpha in the spec.

Known consumers

  • tsanetgit/Connect_Gateway pins connect-library.version 2.0.0. Moving to 3.0.0 is its own change, and the V2 and /v1/ error changes above apply.
  • tsanetgit/Fin-Intercom_App consumes gateway-engine, not the library directly, so it follows the gateway.

Verification

  • CI at the release commit: verify on main 23b7489, built against Connect-API-Code beta 46fc91f, whose spec is byte-identical to the one BETA serves. Every module passed with zero failures:

    Module Tests
    connect-library 297
    scripted demo 9
    console 44
    attachment-receiver 182 (40 environment-gated live tests skipped)
    demo-ui 44

  • Reviews: a whole-branch design review of the promotion (#136), with every finding dispositioned on the PR. Item 1 was fixed in #138. The promotion and #138 each had a separate-session QA review.

  • Live on BETA at the release commit (2026-10-21): the demo-ui image built from 23b7489 sent two V2 attachments as a test member, to a test receiver whose storage is an S3 bucket:

    • Single: a 1 MiB file in single mode, grant completed.
    • Multipart: a 12 MiB file in s3Multipart mode, three 5 MiB parts, grant completed.

    The platform checks the stored upload before it completes a grant. The same image now runs the hosted demo.

Assets 2
Loading