@medalsocial/sdk 1.5.0 → 1.6.0

package/openapi/medal-social.openapi.yaml

@@ -29,10 +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:
@@ -930,6 +939,34 @@ 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]
@@ -962,8 +999,20 @@ paths:
       tags: [Channels]
       operationId: listChannelConnectLinks
       summary: List connect links
-      description: Link tokens are never returned.
+      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:
@@ -974,11 +1023,11 @@ paths:
             $ref: "#/components/schemas/ConnectLinkStatus"
       responses:
         "200":
-          description: The workspace's connect links.
+          description: Connect links page.
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ApiResponse_ConnectLinkArray"
+                $ref: "#/components/schemas/PaginatedResponse_ConnectLink"
         default:
           $ref: "#/components/responses/ApiError"
   /api/v1/channels/connect-links/{id}:
@@ -1005,13 +1054,28 @@ paths:
       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: The workspace's channel connections (generic shape).
+          description: Channel connections page.
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ApiResponse_ChannelConnectionArray"
+                $ref: "#/components/schemas/PaginatedResponse_ChannelConnection"
         default:
           $ref: "#/components/responses/ApiError"
   /api/v1/channels/connections/{id}:
@@ -1035,6 +1099,66 @@ paths:
                 $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:
@@ -2154,6 +2278,8 @@ components:
         - author_user_id
         - author_name
         - body
+        - delivery_status
+        - delivery_error
         - created_at
       properties:
         id:
@@ -2170,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
@@ -2363,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
@@ -2379,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]
@@ -2580,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:
@@ -2604,6 +2779,11 @@ components:
       $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:
@@ -2672,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]
@@ -2802,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]
@@ -2882,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]
@@ -2904,6 +3317,11 @@ components:
           $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:
@@ -2918,6 +3336,11 @@ components:
           $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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medalsocial/sdk",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "TypeScript SDK for Medal Social API — posts, emails, contacts, deals, helpdesk, webhooks, and GDPR compliance",
   "license": "Apache-2.0",
   "author": "Medal Social / Ali Aljumaili",

package/skills/resources/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: resources
-description: Use when calling any of the SDK resources (contacts, deals, emails, gdpr, posts, workspaces) — listing with pagination, sending transactional or batch emails, scheduling and publishing posts, recording GDPR consent or running an export workflow, fetching a contact's activity timeline — or when needing OpenAPI-derived TypeScript types or the raw OpenAPI document from `@medalsocial/sdk`.
+description: Use when calling any of the SDK resources (contacts, deals, emails, gdpr, posts, scan, workspaces) — listing with pagination, sending transactional or batch emails, scheduling and publishing posts, recording GDPR consent or running an export workflow, fetching a contact's activity timeline — or when needing OpenAPI-derived TypeScript types or the raw OpenAPI document from `@medalsocial/sdk`.
 ---
 
 # Medal Social SDK — Resources
 
 ## When to load this skill
 
-- Calling `medal.contacts.*`, `medal.deals.*`, `medal.emails.*`, `medal.gdpr.*`, `medal.posts.*`, or `medal.workspaces.*`.
+- Calling `medal.contacts.*`, `medal.deals.*`, `medal.emails.*`, `medal.gdpr.*`, `medal.posts.*`, `medal.scan.*`, or `medal.workspaces.*`.
 - Looking up an exact method signature or response shape.
 - Building a list view that needs pagination.
 - Sending a single transactional email or a bulk batch.
@@ -35,6 +35,7 @@ Errors throw `MedalApiError` (see the `client` skill for details).
 | `medal.emails.templates` | `src/resources/emails.ts` (`EmailTemplates`) | `list()`, `get(slug, opts?)` |
 | `medal.emails` | `src/resources/emails.ts` (`Emails`) | `send(input)`, `get(id)`, `batch(input)` |
 | `medal.gdpr` | `src/resources/gdpr.ts` | `requestExport()`, `listExports()`, `getExport(id)`, `recordConsent(input)`, `getConsent(email)`, `cookieConsent(input)` |
+| `medal.scan` | `src/resources/scan.ts` | `create(input)` (exactly one of `url`/`orgnr`/`name`; 202 async job), `get(id)`, `companies(q)` (Norwegian registry typeahead), `waitForResult(id, opts?)` (polls until done/failed; returns the job either way, throws only on deadline) |
 | `medal.posts` | `src/resources/posts.ts` | `list(opts?)`, `create(input)`, `get(id)`, `update(id, input)`, `remove(id)`, `schedule(id, input)`, `publish(id)`, `channels()` |
 | `medal.workspaces` | `src/resources/workspaces.ts` | `list()` |