@medalsocial/sdk 1.4.0 → 1.6.0

package/openapi/medal-social.openapi.yaml

@@ -29,6 +29,19 @@ tags:
     description: Read helpdesk conversations, reply, and manage assignment/status.
   - name: Webhooks
     description: Manage webhook endpoints and inspect their deliveries.
+  - name: Capabilities
+    description: >-
+      Mint short-lived capability confirmation tokens for confirmable write
+      routes.
+  - name: Channels
+    description: >-
+      Partner channel connect — mint hosted connect links and manage the
+      resulting channel connections.
+  - name: Scan
+    description: >-
+      Company & website scans (Nettsjekk) — queue a scan by URL, organisation
+      number, or company name, poll the result, and search the Norwegian
+      company registry.
 paths:
   /api/v1/posts:
     get:
@@ -926,6 +939,226 @@ paths:
                 $ref: "#/components/schemas/ApiResponse_WebhookTestResult"
         default:
           $ref: "#/components/responses/ApiError"
+  /api/v1/capability-confirmations:
+    post:
+      tags: [Capabilities]
+      operationId: issueCapabilityConfirmation
+      summary: Issue a capability confirmation token
+      description: >-
+        Mints a short-lived `X-Capability-Confirmation` token for one pending
+        write. Confirmable write routes require BOTH `Idempotency-Key` and
+        `X-Capability-Confirmation` when the credential holds the capability
+        scope directly; API keys with legacy scopes are exempt. The token is
+        bound to the workspace, auth subject, method, path, required scopes and
+        idempotency key, and expires within 15 minutes. `user_approved: true`
+        asserts that a human on the caller's side approved this exact action.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/IssueCapabilityConfirmationInput"
+      responses:
+        "200":
+          description: Minted confirmation token.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_CapabilityConfirmation"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/channels/connect-links:
+    post:
+      tags: [Channels]
+      operationId: createChannelConnectLink
+      summary: Mint a hosted connect link
+      description: >-
+        Mints a single-use hosted connect link that lets an external person
+        (no Medal account required) attach a channel account (e.g.
+        `telegram_inbox`) to the workspace's helpdesk. The response's
+        `data.url` contains the one-time link token EXACTLY ONCE — an
+        idempotent replay (same `Idempotency-Key`) returns the link WITHOUT
+        `url`. Requires the `channel.connect.manage` scope; OAuth callers
+        additionally need the workspace `admin` role.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateConnectLinkInput"
+      responses:
+        "201":
+          description: Minted connect link, including the one-time `url`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_ConnectLinkCreateResult"
+        default:
+          $ref: "#/components/responses/ApiError"
+    get:
+      tags: [Channels]
+      operationId: listChannelConnectLinks
+      summary: List connect links
+      description: >-
+        Link tokens are never returned. Newest first, cursor-paginated. The
+        `channel_type` / `status` filters are applied within each page, so a
+        page may hold fewer than `limit` items while `pagination.has_more` is
+        still true — page off `has_more`, not the item count.
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+          description: Page size (default 50, capped at 100).
+        - $ref: "#/components/parameters/Cursor"
+        - name: channel_type
+          in: query
+          schema:
+            type: string
+        - name: status
+          in: query
+          schema:
+            $ref: "#/components/schemas/ConnectLinkStatus"
+      responses:
+        "200":
+          description: Connect links page.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PaginatedResponse_ConnectLink"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/channels/connect-links/{id}:
+    parameters:
+      - $ref: "#/components/parameters/Id"
+    delete:
+      tags: [Channels]
+      operationId: revokeChannelConnectLink
+      summary: Revoke a connect link
+      description: >-
+        Revokes a pending connect link so it can no longer be consumed. OAuth
+        callers need the workspace `admin` role.
+      responses:
+        "200":
+          description: Revoke result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_ConnectLinkRevokeResult"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/channels/connections:
+    get:
+      tags: [Channels]
+      operationId: listChannelConnections
+      summary: List channel connections
+      description: >-
+        The workspace's channel connections in a generic, channel-agnostic
+        shape. Newest first, cursor-paginated. Rows that are not projectable
+        as connections are dropped within the page, so a page may hold fewer
+        than `limit` items while `pagination.has_more` is still true — page
+        off `has_more`, not the item count.
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+          description: Page size (default 50, capped at 100).
+        - $ref: "#/components/parameters/Cursor"
+      responses:
+        "200":
+          description: Channel connections page.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PaginatedResponse_ChannelConnection"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/channels/connections/{id}:
+    parameters:
+      - $ref: "#/components/parameters/Id"
+    delete:
+      tags: [Channels]
+      operationId: disconnectChannelConnection
+      summary: Disconnect a channel connection
+      description: >-
+        Disconnects a connected channel account (best-effort platform logout,
+        then local revoke). Emits a `helpdesk.channel_disconnected` webhook
+        event with `reason: "api_disconnect"` if the account was previously
+        connected. OAuth callers need the workspace `admin` role.
+      responses:
+        "200":
+          description: Disconnect result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_ChannelConnectionDisconnectResult"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/scan:
+    post:
+      tags: [Scan]
+      operationId: createScan
+      summary: Queue a company/site scan
+      description: >-
+        Queues an asynchronous scan. Provide exactly one of `url`, `orgnr`, or
+        `name`; poll the returned id via `GET /api/v1/scan/{id}`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ScanCreateInput"
+      responses:
+        "202":
+          description: Scan job queued.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_ScanCreateResult"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/scan/companies:
+    get:
+      tags: [Scan]
+      operationId: searchScanCompanies
+      summary: Search the Norwegian company registry
+      parameters:
+        - name: q
+          in: query
+          required: true
+          schema:
+            type: string
+            minLength: 2
+      responses:
+        "200":
+          description: Registry matches (top 5, relevance-ranked).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_ScanCompanyArray"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/scan/{id}:
+    parameters:
+      - $ref: "#/components/parameters/Id"
+    get:
+      tags: [Scan]
+      operationId: getScan
+      summary: Get a scan job
+      responses:
+        "200":
+          description: Scan job status and, once done, the findings payload.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_ScanJob"
+        default:
+          $ref: "#/components/responses/ApiError"
 components:
   securitySchemes:
     bearerAuth:
@@ -2045,6 +2278,8 @@ components:
         - author_user_id
         - author_name
         - body
+        - delivery_status
+        - delivery_error
         - created_at
       properties:
         id:
@@ -2061,9 +2296,26 @@ components:
           type: [string, "null"]
         body:
           type: string
+        delivery_status:
+          oneOf:
+            - $ref: "#/components/schemas/HelpdeskMessageDeliveryStatus"
+            - type: "null"
+          description: >-
+            Outbound delivery state, or `null` for inbound messages and
+            internal notes. A `201` from `POST /api/v1/helpdesk/replies` means
+            the reply was accepted, NOT delivered — the channel hand-off is
+            asynchronous, so poll this field (or subscribe to
+            `helpdesk.message_delivery_updated`) to learn the outcome.
+        delivery_error:
+          type: [string, "null"]
+          description: >-
+            Last send error for a `failed` outbound message, otherwise `null`.
         created_at:
           type: integer
           description: Unix timestamp in milliseconds.
+    HelpdeskMessageDeliveryStatus:
+      type: string
+      enum: [pending, sent, delivered, failed]
     UpdateHelpdeskConversationInput:
       type: object
       minProperties: 1
@@ -2254,9 +2506,22 @@ components:
           const: deleted
     WebhookDelivery:
       type: object
+      description: >-
+        A delivery attempt record. `id` is the same value sent as the
+        `X-Medal-Delivery-Id` and `Idempotency-Key` headers on the outbound
+        request. Deliveries never carry payload bodies (payloads can contain
+        customer PII). The correlation fields are derived from the stored event
+        and fail closed to `null` when no canonical event exists — e.g.
+        `test.ping` deliveries or events that have aged out of retention.
       required:
         - id
         - event_type
+        - resource_id
+        - conversation_id
+        - message_id
+        - connection_ref
+        - channel
+        - channel_connection_id
         - status
         - attempt_count
         - next_attempt_at
@@ -2270,6 +2535,19 @@ components:
           type: string
         event_type:
           type: string
+        resource_id:
+          type: [string, "null"]
+          description: Primary subject id of the announced event, or `null`.
+        conversation_id:
+          type: [string, "null"]
+        message_id:
+          type: [string, "null"]
+        connection_ref:
+          type: [string, "null"]
+        channel:
+          type: [string, "null"]
+        channel_connection_id:
+          type: [string, "null"]
         status:
           type: string
           enum: [pending, delivered, dead_letter]
@@ -2299,6 +2577,130 @@ components:
         status:
           type: string
           const: queued
+    ConnectLinkStatus:
+      type: string
+      enum: [pending, consumed, expired, revoked]
+    ChannelConnectionState:
+      type: string
+      enum: [connecting, active, disconnected, disabled]
+    CreateConnectLinkInput:
+      type: object
+      required: [channel_type]
+      properties:
+        channel_type:
+          type: string
+          maxLength: 64
+          description: Channel type to connect (e.g. `telegram_inbox`).
+        label:
+          type: string
+          maxLength: 100
+          description: Display label shown on the hosted connect page.
+        redirect_url:
+          type: string
+          format: uri
+          maxLength: 2000
+          description: >-
+            URL the hosted page redirects to after a successful connect — must
+            be https.
+    ConnectLinkCreateResult:
+      type: object
+      required: [id, channel_type, label, status, expires_at]
+      properties:
+        id:
+          type: string
+        url:
+          type: string
+          format: uri
+          description: >-
+            Single-use hosted connect URL containing the one-time link token —
+            present ONLY in the live create response. An idempotent replay of
+            the create request omits it; the token can never be retrieved
+            again.
+        channel_type:
+          type: string
+        label:
+          type: [string, "null"]
+        status:
+          $ref: "#/components/schemas/ConnectLinkStatus"
+        expires_at:
+          type: integer
+          description: Unix timestamp in milliseconds.
+    ConnectLink:
+      type: object
+      required:
+        - id
+        - channel_type
+        - label
+        - status
+        - consumed_connection_ref
+        - expires_at
+        - created_at
+      properties:
+        id:
+          type: string
+        channel_type:
+          type: string
+        label:
+          type: [string, "null"]
+        status:
+          $ref: "#/components/schemas/ConnectLinkStatus"
+        consumed_connection_ref:
+          type: [string, "null"]
+          description: >-
+            Stable ref of the connection created by consuming this link, or
+            `null`.
+        expires_at:
+          type: integer
+          description: Unix timestamp in milliseconds.
+        created_at:
+          type: integer
+          description: Unix timestamp in milliseconds.
+    ConnectLinkRevokeResult:
+      type: object
+      required: [id, status]
+      properties:
+        id:
+          type: string
+        status:
+          type: string
+          const: revoked
+    ChannelConnection:
+      type: object
+      required:
+        - id
+        - channel_type
+        - label
+        - state
+        - masked_identity
+        - last_activity_at
+        - helpdesk_connection_id
+      properties:
+        id:
+          type: string
+        channel_type:
+          type: string
+        label:
+          type: [string, "null"]
+        state:
+          $ref: "#/components/schemas/ChannelConnectionState"
+        masked_identity:
+          type: string
+          description: Privacy-preserving identity handle (e.g. a masked phone number).
+        last_activity_at:
+          type: [integer, "null"]
+          description: Unix timestamp in milliseconds, or `null` if never active.
+        helpdesk_connection_id:
+          type: [string, "null"]
+          description: Linked helpdesk channel connection ID, or `null`.
+    ChannelConnectionDisconnectResult:
+      type: object
+      required: [id, state]
+      properties:
+        id:
+          type: string
+        state:
+          type: string
+          const: disconnected
     ApiResponse_PostCreateResult:
       $ref: "#/components/schemas/Envelope_PostCreateResult"
     ApiResponse_PostDetail:
@@ -2347,6 +2749,12 @@ components:
       $ref: "#/components/schemas/Envelope_GdprExportArray"
     ApiResponse_GdprExport:
       $ref: "#/components/schemas/Envelope_GdprExport"
+    ApiResponse_ScanCreateResult:
+      $ref: "#/components/schemas/Envelope_ScanCreateResult"
+    ApiResponse_ScanCompanyArray:
+      $ref: "#/components/schemas/Envelope_ScanCompanyArray"
+    ApiResponse_ScanJob:
+      $ref: "#/components/schemas/Envelope_ScanJob"
     ApiResponse_ConsentResult:
       $ref: "#/components/schemas/Envelope_ConsentResult"
     ApiResponse_ConsentRecordArray:
@@ -2369,6 +2777,21 @@ components:
       $ref: "#/components/schemas/Envelope_WebhookDeliveryArray"
     ApiResponse_WebhookTestResult:
       $ref: "#/components/schemas/Envelope_WebhookTestResult"
+    ApiResponse_ConnectLinkCreateResult:
+      $ref: "#/components/schemas/Envelope_ConnectLinkCreateResult"
+    # Deprecated: the channels listings are cursor-paginated and now respond
+    # with PaginatedResponse_ConnectLink / PaginatedResponse_ChannelConnection.
+    # These unpaginated aliases are retained (unreferenced by any operation)
+    # so consumers importing the generated contract via
+    # `@medalsocial/sdk/openapi-types` or `OpenApiComponents` keep compiling.
+    ApiResponse_ConnectLinkArray:
+      $ref: "#/components/schemas/Envelope_ConnectLinkArray"
+    ApiResponse_ConnectLinkRevokeResult:
+      $ref: "#/components/schemas/Envelope_ConnectLinkRevokeResult"
+    ApiResponse_ChannelConnectionArray:
+      $ref: "#/components/schemas/Envelope_ChannelConnectionArray"
+    ApiResponse_ChannelConnectionDisconnectResult:
+      $ref: "#/components/schemas/Envelope_ChannelConnectionDisconnectResult"
     PaginatedResponse_Post:
       type: object
       required: [data, pagination]
@@ -2429,6 +2852,26 @@ components:
             $ref: "#/components/schemas/HelpdeskMessage"
         pagination:
           $ref: "#/components/schemas/Pagination"
+    PaginatedResponse_ConnectLink:
+      type: object
+      required: [data, pagination]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/ConnectLink"
+        pagination:
+          $ref: "#/components/schemas/Pagination"
+    PaginatedResponse_ChannelConnection:
+      type: object
+      required: [data, pagination]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/ChannelConnection"
+        pagination:
+          $ref: "#/components/schemas/Pagination"
     Envelope_PostCreateResult:
       type: object
       required: [data]
@@ -2559,6 +3002,131 @@ components:
       properties:
         data:
           $ref: "#/components/schemas/DealRemoveResult"
+    ScanCreateInput:
+      type: object
+      description: Provide exactly one of `url`, `orgnr`, or `name`.
+      oneOf:
+        - required: [url]
+          not:
+            anyOf: [{ required: [orgnr] }, { required: [name] }]
+        - required: [orgnr]
+          not:
+            anyOf: [{ required: [url] }, { required: [name] }]
+        - required: [name]
+          not:
+            anyOf: [{ required: [url] }, { required: [orgnr] }]
+      properties:
+        url:
+          type: string
+          minLength: 4
+          maxLength: 500
+        orgnr:
+          type: string
+          pattern: "^\\d{9}$"
+        name:
+          type: string
+          minLength: 2
+          maxLength: 120
+    ScanCreateResult:
+      type: object
+      required: [id, status]
+      properties:
+        id:
+          type: string
+        status:
+          type: string
+        message:
+          type: string
+    ScanCompany:
+      type: object
+      required: [orgnr, name, org_form, industry, city, website]
+      properties:
+        orgnr:
+          type: string
+        name:
+          type: string
+        org_form:
+          type: [string, "null"]
+        industry:
+          type: [string, "null"]
+        city:
+          type: [string, "null"]
+        website:
+          type: [string, "null"]
+    ScanJob:
+      type: object
+      required: [id, status, input, resolved, result, error, created_at, finished_at]
+      properties:
+        id:
+          type: string
+        status:
+          type: string
+          description: pending | running | done | failed
+        input:
+          $ref: "#/components/schemas/ScanCreateInput"
+        resolved:
+          type: [object, "null"]
+          properties:
+            orgnr:
+              type: string
+            companyName:
+              type: string
+            websiteUrl:
+              type: string
+        result:
+          type: [object, "null"]
+          description: >-
+            Versioned findings payload (see the SDK `ScanResultPayload` type);
+            additive per `version`. The stable core is documented below;
+            further sections (registry, signals, pagespeed, seo, ai, gdpr,
+            mailAuth, httpsOk) evolve additively.
+          required: [version, nettskaar, subScores]
+          properties:
+            version:
+              type: integer
+            nettskaar:
+              type: [integer, "null"]
+              description: Weighted composite score (0-100); null when unmeasurable.
+            subScores:
+              type: object
+              description: Per-axis 0-100 scores; null axes were unmeasurable.
+              required: [fart, google, ai, trygghet, omdomme]
+              properties:
+                fart: { type: [integer, "null"] }
+                google: { type: [integer, "null"] }
+                ai: { type: [integer, "null"] }
+                trygghet: { type: [integer, "null"] }
+                omdomme: { type: [integer, "null"] }
+          additionalProperties: true
+        error:
+          type: [string, "null"]
+          description: Public-safe failure code (company_not_found, no_website, …).
+        created_at:
+          type: [string, "null"]
+          format: date-time
+        finished_at:
+          type: [string, "null"]
+          format: date-time
+    Envelope_ScanCreateResult:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/ScanCreateResult"
+    Envelope_ScanCompanyArray:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/ScanCompany"
+    Envelope_ScanJob:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/ScanJob"
     Envelope_GdprExportRequest:
       type: object
       required: [data]
@@ -2639,6 +3207,94 @@ components:
       properties:
         data:
           $ref: "#/components/schemas/WebhookDeleteResult"
+    IssueCapabilityConfirmationInput:
+      type: object
+      required: [capability_id, preview_summary, user_approved]
+      properties:
+        capability_id:
+          type: string
+          minLength: 1
+          maxLength: 160
+          description: Confirmable capability to mint a token for.
+        api_path:
+          type: string
+          minLength: 1
+          maxLength: 512
+          description: >-
+            Concrete `/api/v1/...` path to bind the token to. Optional when the
+            capability has exactly one API target; required when it has several.
+        path_params:
+          type: object
+          additionalProperties:
+            type: [string, number, boolean]
+          description: Values for the capability path template's parameters.
+        idempotency_key:
+          type: string
+          minLength: 1
+          description: >-
+            The exact `Idempotency-Key` the confirmed write will send. The token
+            is bound to it.
+        preview_summary:
+          type: string
+          minLength: 1
+          maxLength: 4000
+          description: >-
+            Human-readable description of the approved action, retained for
+            audit.
+        user_approved:
+          const: true
+          description: >-
+            Asserts that a human on the caller's side approved this specific
+            action.
+    CapabilityConfirmation:
+      type: object
+      required:
+        - confirmation_token
+        - token_type
+        - capability_id
+        - method
+        - path
+        - required_scopes
+        - idempotency_key
+        - expires_in
+        - expires_at
+        - preview_summary
+      properties:
+        confirmation_token:
+          type: string
+          description: Send as the `X-Capability-Confirmation` header on the write.
+        token_type:
+          type: string
+          const: medal_capability_confirmation
+        capability_id:
+          type: string
+        method:
+          type: string
+        path:
+          type: string
+        required_scopes:
+          type: array
+          items:
+            type: string
+        idempotency_key:
+          type: [string, "null"]
+        expires_in:
+          type: integer
+          minimum: 60
+          maximum: 900
+        expires_at:
+          type: string
+          format: date-time
+        preview_summary:
+          type: string
+    ApiResponse_CapabilityConfirmation:
+      $ref: "#/components/schemas/Envelope_CapabilityConfirmation"
+    Envelope_CapabilityConfirmation:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/CapabilityConfirmation"
     Envelope_WebhookDeliveryArray:
       type: object
       required: [data]
@@ -2653,3 +3309,47 @@ components:
       properties:
         data:
           $ref: "#/components/schemas/WebhookTestResult"
+    Envelope_ConnectLinkCreateResult:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/ConnectLinkCreateResult"
+    Envelope_ConnectLinkArray:
+      type: object
+      deprecated: true
+      description: >-
+        Deprecated — `listChannelConnectLinks` responds with
+        `PaginatedResponse_ConnectLink`. Retained for backwards compatibility
+        with consumers of the generated contract types.
+      required: [data]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/ConnectLink"
+    Envelope_ConnectLinkRevokeResult:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/ConnectLinkRevokeResult"
+    Envelope_ChannelConnectionArray:
+      type: object
+      deprecated: true
+      description: >-
+        Deprecated — `listChannelConnections` responds with
+        `PaginatedResponse_ChannelConnection`. Retained for backwards
+        compatibility with consumers of the generated contract types.
+      required: [data]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/ChannelConnection"
+    Envelope_ChannelConnectionDisconnectResult:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/ChannelConnectionDisconnectResult"