@ziggs-ai/api-client 0.1.14 → 0.1.16

package/dist/http/AgreementClient.d.ts

@@ -1,10 +1,13 @@
 import 'dotenv/config';
-import { type Creds, type Agreement, type EngagementKind } from '../types.js';
+import { type Creds, type Agreement, type EngagementKind, type BroadcastAudience } from '../types.js';
 import { type PublishToLedgerPayload } from './TaskClient.js';
 export type PlanReviewTiming = 'with_proposal' | 'before_execution';
 /**
  * Shared proposal terms. When `engagementKind` is omitted the server defaults to `service`.
- * Use `proposedTo: OPEN_AGREEMENT_TARGET` (`"everyone"`) for open buyer-broadcast quests.
+ * For an open buyer-broadcast quest, set `proposedTo` to a broadcast sentinel —
+ * `OPEN_AGREEMENT_TARGET` (`"everyone"`, fully public) or `ORG_AGREEMENT_TARGET`
+ * (`"org"`, scoped to your org). Prefer `proposeBroadcast({ audience })` over
+ * setting `proposedTo` by hand.
  */
 export interface ProposeTerms {
     description: string;
@@ -29,14 +32,25 @@ export interface ProposeDirectInput extends ProposeTerms {
     proposedTo: string;
     chatId: string;
 }
-/** Open buyer-broadcast: any agent may claim (`proposedTo` is set to `"everyone"`). */
-export type ProposeBroadcastInput = Omit<ProposeDirectInput, 'proposedTo'>;
+/**
+ * Open buyer-broadcast. `audience` selects who may see/claim it:
+ * 'everyone' (default) = fully public; 'org' = members of the creator's active
+ * org only. Sets `proposedTo` to the matching sentinel server-side. When
+ * `audience: 'org'` the creator must have an active org or the server 400s.
+ */
+export type ProposeBroadcastInput = Omit<ProposeDirectInput, 'proposedTo'> & {
+    audience?: BroadcastAudience;
+};
 /** @deprecated Alias for {@link ProposeDirectInput}. */
 export type ProposeAgreementData = ProposeDirectInput;
 export declare function proposeAgreement(proposalData: ProposeDirectInput, creds: Creds): Promise<Agreement>;
 /** Propose a contract to one party (user or agent). Server defaults `engagementKind` to `service`. */
 export declare function proposeDirectTo(input: ProposeDirectInput, creds: Creds): Promise<Agreement>;
-/** Propose an open quest (`proposedTo: "everyone"`). Server defaults `engagementKind` to `service`. */
+/**
+ * Propose an open quest. `audience` ('everyone' default | 'org') picks the
+ * broadcast sentinel written to `proposedTo`. Server defaults `engagementKind`
+ * to `service`.
+ */
 export declare function proposeBroadcast(input: ProposeBroadcastInput, creds: Creds): Promise<Agreement>;
 export interface DelegateAgreementData {
     description: string;
@@ -59,8 +73,10 @@ export declare function delegateAgreement(proposalData: DelegateAgreementData, c
 /**
  * Approve or reject a pending agreement (ZIG-524 canonical client path).
  *
- * Routes to `POST /claim` (open broadcast) or `PUT /approvals/:partyId` (ledger).
- * Legacy rows without approvals[] are backfilled server-side on PUT.
+ * Routes to `POST /claim` (open or org-scoped broadcast) or
+ * `PUT /approvals/:partyId` (ledger). Legacy rows without approvals[] are
+ * backfilled server-side on PUT. The server rejects a /claim from a non-member
+ * of an org-scoped broadcast's org.
  */
 export declare function respondToAgreement(agreementId: string, action: 'approve' | 'reject', creds: Creds, opts?: {
     ownerUserId?: string | null;
@@ -134,7 +150,9 @@ export declare function revokeAgreement(agreementId: string, creds: Creds): Prom
 /**
  * Claim an open agreement (ZIG-524 phase 2 / ZIG-525):
  * - open link invite (`engagementKind: link`, proposedTo everyone)
- * - open broadcast quest (proposedTo everyone, status open)
+ * - open broadcast quest (proposedTo 'everyone', status open)
+ * - org-scoped broadcast quest (proposedTo 'org') — the server rejects the
+ *   claim with 403 if the caller is not a member of the agreement's orgId
  *
  * POST /agreements/:id/claim — canonical; no partyId in body.
  */
@@ -164,7 +182,7 @@ export declare function getArtifactsForAgreement(agreementId: string, creds: Cre
 export type UserRole = 'payer' | 'provider' | 'participant' | 'observer';
 export declare function linkUserToAgreement(agreementId: string, userId: string, role: UserRole, creds: Creds): Promise<unknown | null>;
 export declare function getUsersForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
-/** @deprecated Routing is expressed via `proposedTo` (specific id vs `OPEN_AGREEMENT_TARGET`), not engagementKind. */
+/** @deprecated Routing is expressed via `proposedTo` (a specific principal id vs a broadcast sentinel — `OPEN_AGREEMENT_TARGET` ('everyone') or `ORG_AGREEMENT_TARGET` ('org')), not engagementKind. */
 export type ContractKind = 'direct' | 'delegate' | 'open';
 interface ContractBase extends Omit<ProposeTerms, 'description'> {
     description: string;
@@ -192,7 +210,11 @@ export type CreateContractInput = DirectContract | DelegateContract | OpenContra
  * {@link delegateAgreement}, or {@link publishOpenQuest}.
  */
 export declare function createContract(input: CreateContractInput, creds: Creds): Promise<Agreement>;
-/** Publish a buyer-broadcast quest to the marketplace ledger (Store "Wanted"). */
+/**
+ * Publish a buyer-broadcast quest to the marketplace ledger (Store "Wanted").
+ * Pass `payload.audience: 'org'` to scope it to your active org (default
+ * `'everyone'`, fully public).
+ */
 export declare function publishOpenQuest(payload: PublishToLedgerPayload, creds: Creds): Promise<Agreement>;
 export declare class AgreementClient {
     private creds;

package/dist/http/AgreementClient.js

@@ -1,7 +1,7 @@
 import 'dotenv/config';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
-import { OPEN_AGREEMENT_TARGET, ApiError } from '../types.js';
+import { OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, ApiError } from '../types.js';
 import { publishToLedger } from './TaskClient.js';
 // Lazy: read at call time so dotenv loaded after this module is imported
 // still takes effect. Baking it at module-load time would freeze the URL
@@ -65,9 +65,15 @@ export async function proposeAgreement(proposalData, creds) {
 export async function proposeDirectTo(input, creds) {
     return proposeAgreement(input, creds);
 }
-/** Propose an open quest (`proposedTo: "everyone"`). Server defaults `engagementKind` to `service`. */
+/**
+ * Propose an open quest. `audience` ('everyone' default | 'org') picks the
+ * broadcast sentinel written to `proposedTo`. Server defaults `engagementKind`
+ * to `service`.
+ */
 export async function proposeBroadcast(input, creds) {
-    return proposeAgreement({ ...input, proposedTo: OPEN_AGREEMENT_TARGET }, creds);
+    const { audience, ...terms } = input;
+    const proposedTo = audience === ORG_AGREEMENT_TARGET ? ORG_AGREEMENT_TARGET : OPEN_AGREEMENT_TARGET;
+    return proposeAgreement({ ...terms, proposedTo }, creds);
 }
 export async function delegateAgreement(proposalData, creds) {
     if (!proposalData)
@@ -106,8 +112,10 @@ export async function delegateAgreement(proposalData, creds) {
 /**
  * Approve or reject a pending agreement (ZIG-524 canonical client path).
  *
- * Routes to `POST /claim` (open broadcast) or `PUT /approvals/:partyId` (ledger).
- * Legacy rows without approvals[] are backfilled server-side on PUT.
+ * Routes to `POST /claim` (open or org-scoped broadcast) or
+ * `PUT /approvals/:partyId` (ledger). Legacy rows without approvals[] are
+ * backfilled server-side on PUT. The server rejects a /claim from a non-member
+ * of an org-scoped broadcast's org.
  */
 export async function respondToAgreement(agreementId, action, creds, opts = {}) {
     if (!agreementId || !action)
@@ -118,7 +126,7 @@ export async function respondToAgreement(agreementId, action, creds, opts = {})
         throw new Error(`Agreement ${agreementId} not found`);
     }
     const proposedTo = agreement.parties?.proposedTo;
-    if (proposedTo === OPEN_AGREEMENT_TARGET) {
+    if (isBroadcastTarget(proposedTo)) {
         if (action === 'reject')
             return agreement;
         const { agreement: updated } = await claimAgreement(agreementId, creds);
@@ -345,7 +353,9 @@ export async function revokeAgreement(agreementId, creds) {
 /**
  * Claim an open agreement (ZIG-524 phase 2 / ZIG-525):
  * - open link invite (`engagementKind: link`, proposedTo everyone)
- * - open broadcast quest (proposedTo everyone, status open)
+ * - open broadcast quest (proposedTo 'everyone', status open)
+ * - org-scoped broadcast quest (proposedTo 'org') — the server rejects the
+ *   claim with 403 if the caller is not a member of the agreement's orgId
  *
  * POST /agreements/:id/claim — canonical; no partyId in body.
  */
@@ -559,7 +569,11 @@ export async function createContract(input, creds) {
         return delegateAgreement(rest, creds);
     return publishOpenQuest(rest, creds);
 }
-/** Publish a buyer-broadcast quest to the marketplace ledger (Store "Wanted"). */
+/**
+ * Publish a buyer-broadcast quest to the marketplace ledger (Store "Wanted").
+ * Pass `payload.audience: 'org'` to scope it to your active org (default
+ * `'everyone'`, fully public).
+ */
 export async function publishOpenQuest(payload, creds) {
     return publishToLedger(payload, creds);
 }

package/dist/http/ArtifactsClient.d.ts

@@ -20,6 +20,8 @@ export interface WriteArtifactInput {
     chatId?: string;
     /** When the artifact is associated with an agreement. */
     agreementId?: string;
+    /** Optional task binding — creates a TaskArtifactLink alongside the primary scope link. */
+    taskId?: string;
     service?: Record<string, unknown>;
 }
 /**

package/dist/http/ArtifactsClient.js

@@ -70,6 +70,7 @@ export class ArtifactsClient {
                 visibility: input.visibility ?? 'chat',
                 chatId: input.chatId,
                 agreementId: input.agreementId,
+                taskId: input.taskId,
                 service: input.service,
             }),
         });

package/dist/http/MarketplaceClient.d.ts

@@ -1,5 +1,5 @@
 import 'dotenv/config';
-import { type Creds, type Agreement } from '../types.js';
+import { type Creds, type Agreement, type BroadcastAudience } from '../types.js';
 export interface PublishOfferPayload {
     description: string;
     price?: number;
@@ -8,6 +8,8 @@ export interface PublishOfferPayload {
     maxExecutions?: number;
     /** `hire` = claimer becomes the provider's principal on claim. Defaults to `service` server-side. */
     engagementKind?: 'hire' | 'service';
+    /** Broadcast audience: 'everyone' (default, fully public) or 'org' (members of your active org only). */
+    audience?: BroadcastAudience;
     metadata?: Record<string, unknown>;
 }
 export declare function publishOffer(payload: PublishOfferPayload, creds: Creds): Promise<Agreement>;

package/dist/http/TaskClient.d.ts

@@ -1,5 +1,5 @@
 import 'dotenv/config';
-import { type Creds, type Task, type TaskState, type Agreement } from '../types.js';
+import { type Creds, type Task, type TaskState, type Agreement, type BroadcastAudience } from '../types.js';
 export interface CreateTaskData {
     description: string;
     agreementId: string;
@@ -34,6 +34,8 @@ export interface PublishToLedgerPayload {
     expiresAt?: string;
     maxExecutions?: number;
     agreementDescription?: string;
+    /** Broadcast audience: 'everyone' (default, fully public) or 'org' (members of your active org only). */
+    audience?: BroadcastAudience;
 }
 export declare function publishToLedger(payload: PublishToLedgerPayload, creds: Creds): Promise<Agreement>;
 export interface PullFromLedgerOptions {

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export * from './http/index.js';
 export { WebSocketClient } from './websocket/index.js';
 export { createControlSocket } from './websocket/ControlSocket.js';
 export { ConnectionManager } from './ConnectionManager.js';
-export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
+export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
-export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, EntryType, ContentType, MessageMetadata, MessageHandler, ApiError, } from './types.js';
+export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, ApiError, } from './types.js';
 export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, } from './http/AgreementClient.js';

package/dist/index.js

@@ -2,6 +2,6 @@ export * from './http/index.js';
 export { WebSocketClient } from './websocket/index.js';
 export { createControlSocket } from './websocket/ControlSocket.js';
 export { ConnectionManager } from './ConnectionManager.js';
-export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
+export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';

package/dist/types.d.ts

@@ -105,8 +105,16 @@ export declare const ContentTypes: {
 export type ContentType = (typeof ContentTypes)[keyof typeof ContentTypes];
 /** ⚠️ SYNC: Mirrors backend src/chat/chat.types.ts isValidContentType */
 export declare function isValidContentType(contentType: string, entryType: string): boolean;
-/** ⚠️ SYNC: Keep in sync with backend. This is the canonical SDK-side definition. */
+/** ⚠️ SYNC: Keep in sync with backend agreements.constants.ts. Fully-public broadcast sentinel. */
 export declare const OPEN_AGREEMENT_TARGET: "everyone";
+/** ⚠️ SYNC: backend ORG_AGREEMENT_TARGET. Org-scoped broadcast: visible/claimable only by members of the agreement's orgId. */
+export declare const ORG_AGREEMENT_TARGET: "org";
+/** Audience for a broadcast proposal: fully public ('everyone') or org-scoped ('org'). */
+export type BroadcastAudience = typeof OPEN_AGREEMENT_TARGET | typeof ORG_AGREEMENT_TARGET;
+/** Both broadcast sentinels — values that occupy a party slot but are NOT real principal ids. */
+export declare const BROADCAST_TARGETS: readonly ["everyone", "org"];
+/** True when `id` is a broadcast sentinel ('everyone' | 'org') rather than a concrete principal id. */
+export declare function isBroadcastTarget(id: string | null | undefined): boolean;
 export interface MessageMetadata {
     chatId: string;
     /** Stable id for dedup across push + inbox catch-up (ZIG-454). */

package/dist/types.js

@@ -48,5 +48,13 @@ const VALID_CONTENT_TYPES = {
 export function isValidContentType(contentType, entryType) {
     return VALID_CONTENT_TYPES[entryType]?.includes(contentType) ?? false;
 }
-/** ⚠️ SYNC: Keep in sync with backend. This is the canonical SDK-side definition. */
+/** ⚠️ SYNC: Keep in sync with backend agreements.constants.ts. Fully-public broadcast sentinel. */
 export const OPEN_AGREEMENT_TARGET = 'everyone';
+/** ⚠️ SYNC: backend ORG_AGREEMENT_TARGET. Org-scoped broadcast: visible/claimable only by members of the agreement's orgId. */
+export const ORG_AGREEMENT_TARGET = 'org';
+/** Both broadcast sentinels — values that occupy a party slot but are NOT real principal ids. */
+export const BROADCAST_TARGETS = [OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET];
+/** True when `id` is a broadcast sentinel ('everyone' | 'org') rather than a concrete principal id. */
+export function isBroadcastTarget(id) {
+    return id === OPEN_AGREEMENT_TARGET || id === ORG_AGREEMENT_TARGET;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",