@augno/sdk 0.1.9 → 0.7.1

package/src/resources/identity/roles.ts

@@ -11,28 +11,24 @@ import { path } from '../../internal/utils/path';
  */
 export class Roles extends APIResource {
   /**
-   * Creates a new role with the specified permissions.
+   * Returns a paginated list of roles for the target account, including global
+   * roles.
+   *
+   * This endpoint requires the permission: `roles:read`.
    *
    * @example
    * ```ts
-   * const role = await client.identity.roles.create({
-   *   name: 'Warehouse Manager',
-   *   permissions: [
-   *     'customers:create',
-   *     'customers:read',
-   *     'customers:update',
-   *     'invoices:read',
-   *   ],
-   * });
+   * const listRole = await client.identity.roles.list();
    * ```
    */
-  create(params: RoleCreateParams, options?: RequestOptions): APIPromise<APIKeysAPI.Role> {
-    const { include, ...body } = params;
-    return this._client.post('/v1/identity/roles', { query: { include }, body, ...options });
+  list(query: RoleListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListRole> {
+    return this._client.get('/v1/identity/roles', { query, ...options });
   }
 
   /**
-   * Returns a role by ID, including its structured permissions.
+   * Returns a role by ID, including its permissions.
+   *
+   * This endpoint requires the permission: `roles:read`.
    *
    * @example
    * ```ts
@@ -50,13 +46,45 @@ export class Roles extends APIResource {
   }
 
   /**
-   * Partially updates a custom role's name or permissions. Provided permissions
-   * replace all existing ones; global roles cannot be modified.
+   * Creates a custom role with the specified permissions.
+   *
+   * Roles created through the API always have type `user`.
+   *
+   * This endpoint requires the permission: `roles:create`.
+   *
+   * @example
+   * ```ts
+   * const role = await client.identity.roles.create({
+   *   name: 'Warehouse Manager',
+   *   permissions: [
+   *     'customers:create',
+   *     'customers:read',
+   *     'customers:update',
+   *     'invoices:read',
+   *   ],
+   * });
+   * ```
+   */
+  create(params: RoleCreateParams, options?: RequestOptions): APIPromise<APIKeysAPI.Role> {
+    const { include, ...body } = params;
+    return this._client.post('/v1/identity/roles', { query: { include }, body, ...options });
+  }
+
+  /**
+   * Partially updates a custom role's name or permissions.
+   *
+   * Provided permissions replace all existing ones; global roles cannot be modified.
+   *
+   * This endpoint requires the permission: `roles:update`.
    *
    * @example
    * ```ts
    * const role = await client.identity.roles.update(
    *   'rl_01c16d2eb637c0d1f3a372937c',
+   *   {
+   *     name: 'Updated Manager',
+   *     permissions: ['customers:read', 'customers:update'],
+   *   },
    * );
    * ```
    */
@@ -70,20 +98,12 @@ export class Roles extends APIResource {
   }
 
   /**
-   * Returns a paginated list of roles for the target account, including global
-   * roles.
+   * Deletes a role and its associated permissions.
    *
-   * @example
-   * ```ts
-   * const listRole = await client.identity.roles.list();
-   * ```
-   */
-  list(query: RoleListParams | null | undefined = {}, options?: RequestOptions): APIPromise<ListRole> {
-    return this._client.get('/v1/identity/roles', { query, ...options });
-  }
-
-  /**
-   * Deletes a role and its associated permissions. Global roles cannot be deleted.
+   * Global roles and roles currently assigned to one or more users cannot be
+   * deleted.
+   *
+   * This endpoint requires the permission: `roles:delete`.
    *
    * @example
    * ```ts
@@ -102,14 +122,17 @@ export class Roles extends APIResource {
  */
 export interface CreateRoleRequest {
   /**
-   * Display name.
+   * Display name for the role, unique within the account.
    */
   name: string;
 
   /**
-   * Permissions to attach in `<domain>:<action>` format.
+   * Permissions to grant, in `{domain}:{action}` format, such as `customers:read`.
+   *
+   * The action must be one of `create`, `read`, `update`, or `delete`. Omit to
+   * create a role with no permissions.
    */
-  permissions: Array<string>;
+  permissions?: Array<string>;
 }
 
 /**
@@ -137,35 +160,56 @@ export interface ListRole {
  */
 export interface UpdateRoleRequest {
   /**
-   * Display name.
+   * New display name for the role, unique within the account.
+   *
+   * Omit to leave unchanged.
    */
   name?: string;
 
   /**
-   * Permissions in `<domain>:<action>` format. Replaces all existing permissions;
-   * omit to leave unchanged.
+   * Full replacement set of permissions, in `{domain}:{action}` format, such as
+   * `customers:read`.
+   *
+   * Replaces all existing permissions on the role. Pass an empty array to remove all
+   * permissions, or omit to leave them unchanged.
    */
   permissions?: Array<string>;
 }
 
 export interface RoleDeleteResponse {}
 
-export interface RoleCreateParams {
+export interface RoleListParams {
   /**
-   * Body param: Display name.
+   * Opaque cursor token identifying where the page of results starts.
+   *
+   * Use the `cursor` value embedded in a previous response's `next_page_url` or
+   * `previous_page_url` to fetch the adjacent page. Omit to start from the first
+   * page.
    */
-  name: string;
+  cursor?: string;
 
   /**
-   * Body param: Permissions to attach in `<domain>:<action>` format.
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
    */
-  permissions: Array<string>;
+  include?: Array<'owner' | 'owner.account' | 'permissions'>;
 
   /**
-   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
-   * are returned as `null`.
+   * Maximum number of results to return in a single page.
    */
-  include?: Array<'owner' | 'owner.account' | 'permissions'>;
+  limit?: number;
+
+  /**
+   * Free-text search term used to filter results.
+   *
+   * Which fields are matched against the term varies by endpoint.
+   */
+  q?: string;
+
+  /**
+   * Filter results to roles whose type matches any of the given values.
+   */
+  types?: Array<'admin' | 'user' | 'scanner' | 'sales_rep' | 'agent'>;
 }
 
 export interface RoleRetrieveParams {
@@ -176,51 +220,50 @@ export interface RoleRetrieveParams {
   include?: Array<'owner' | 'owner.account' | 'permissions'>;
 }
 
-export interface RoleUpdateParams {
+export interface RoleCreateParams {
   /**
-   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
-   * are returned as `null`.
+   * Body param: Display name for the role, unique within the account.
    */
-  include?: Array<'owner' | 'owner.account' | 'permissions'>;
+  name: string;
 
   /**
-   * Body param: Display name.
+   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
+   * are returned as `null`.
    */
-  name?: string;
+  include?: Array<'owner' | 'owner.account' | 'permissions'>;
 
   /**
-   * Body param: Permissions in `<domain>:<action>` format. Replaces all existing
-   * permissions; omit to leave unchanged.
+   * Body param: Permissions to grant, in `{domain}:{action}` format, such as
+   * `customers:read`.
+   *
+   * The action must be one of `create`, `read`, `update`, or `delete`. Omit to
+   * create a role with no permissions.
    */
   permissions?: Array<string>;
 }
 
-export interface RoleListParams {
-  /**
-   * Cursor token used to retrieve the next or previous page of results.
-   */
-  cursor?: string;
-
+export interface RoleUpdateParams {
   /**
-   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
-   * `null`.
+   * Query param: Sub-objects to expand in the response. When omitted, sub-objects
+   * are returned as `null`.
    */
   include?: Array<'owner' | 'owner.account' | 'permissions'>;
 
   /**
-   * Maximum number of results per page (default: 100, max: 1000).
-   */
-  limit?: number;
-
-  /**
-   * Search query used to filter results.
+   * Body param: New display name for the role, unique within the account.
+   *
+   * Omit to leave unchanged.
    */
-  q?: string;
+  name?: string;
 
   /**
-   * Filter by role types.
+   * Body param: Full replacement set of permissions, in `{domain}:{action}` format,
+   * such as `customers:read`.
+   *
+   * Replaces all existing permissions on the role. Pass an empty array to remove all
+   * permissions, or omit to leave them unchanged.
    */
-  types?: Array<'admin' | 'user' | 'scanner' | 'sales_rep' | 'agent'>;
+  permissions?: Array<string>;
 }
 
 export declare namespace Roles {
@@ -229,9 +272,9 @@ export declare namespace Roles {
     type ListRole as ListRole,
     type UpdateRoleRequest as UpdateRoleRequest,
     type RoleDeleteResponse as RoleDeleteResponse,
-    type RoleCreateParams as RoleCreateParams,
+    type RoleListParams as RoleListParams,
     type RoleRetrieveParams as RoleRetrieveParams,
+    type RoleCreateParams as RoleCreateParams,
     type RoleUpdateParams as RoleUpdateParams,
-    type RoleListParams as RoleListParams,
   };
 }

package/src/resources/index.ts

@@ -2,7 +2,7 @@
 
 export { Auth } from './auth/auth';
 export { Catalog } from './catalog/catalog';
-export { Core } from './core/core';
+export { Core, type Entity, type ListEntity, type CoreRetrieveSearchParams } from './core/core';
 export {
   Finance,
   type AdjustmentType,
@@ -11,10 +11,12 @@ export {
   type ListTransactionType,
   type TransactionMethod,
   type TransactionType,
-  type FinanceRetrieveAdjustmentTypesParams,
-  type FinanceRetrieveTransactionMethodsParams,
   type FinanceRetrieveTransactionTypesParams,
+  type FinanceRetrieveTransactionMethodsParams,
+  type FinanceRetrieveAdjustmentTypesParams,
 } from './finance/finance';
 export { Identity } from './identity/identity';
+export { Messaging, type ListActor, type MessagingRetrieveContactsParams } from './messaging/messaging';
 export { Operations } from './operations/operations';
 export { Sales } from './sales/sales';
+export { Settings } from './settings/settings';

package/src/resources/messaging/announcements/actions.ts

@@ -0,0 +1,119 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as AnnouncementsAPI from './announcements';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * List, read, and manage broadcast announcements.
+ */
+export class Actions extends APIResource {
+  /**
+   * Marks an announcement as seen for the calling actor.
+   *
+   * This endpoint requires the permission: `messaging:update`.
+   *
+   * @example
+   * ```ts
+   * const announcement =
+   *   await client.messaging.announcements.actions.seen(
+   *     'an_01c4d5e6f7a8b9c0d1e2f3a4',
+   *   );
+   * ```
+   */
+  seen(
+    id: string,
+    params: ActionSeenParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<AnnouncementsAPI.Announcement> {
+    const { include } = params ?? {};
+    return this._client.post(path`/v1/messaging/announcements/${id}/actions/seen`, {
+      query: { include },
+      ...options,
+    });
+  }
+
+  /**
+   * Marks an announcement as read for the calling actor.
+   *
+   * This endpoint requires the permission: `messaging:update`.
+   *
+   * @example
+   * ```ts
+   * const announcement =
+   *   await client.messaging.announcements.actions.read(
+   *     'an_01c4d5e6f7a8b9c0d1e2f3a4',
+   *   );
+   * ```
+   */
+  read(
+    id: string,
+    params: ActionReadParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<AnnouncementsAPI.Announcement> {
+    const { include } = params ?? {};
+    return this._client.post(path`/v1/messaging/announcements/${id}/actions/read`, {
+      query: { include },
+      ...options,
+    });
+  }
+
+  /**
+   * Marks an announcement as dismissed for the calling actor.
+   *
+   * This endpoint requires the permission: `messaging:update`.
+   *
+   * @example
+   * ```ts
+   * const announcement =
+   *   await client.messaging.announcements.actions.dismiss(
+   *     'an_01c4d5e6f7a8b9c0d1e2f3a4',
+   *   );
+   * ```
+   */
+  dismiss(
+    id: string,
+    params: ActionDismissParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<AnnouncementsAPI.Announcement> {
+    const { include } = params ?? {};
+    return this._client.post(path`/v1/messaging/announcements/${id}/actions/dismiss`, {
+      query: { include },
+      ...options,
+    });
+  }
+}
+
+export interface ActionSeenParams {
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
+   */
+  include?: Array<'resource'>;
+}
+
+export interface ActionReadParams {
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
+   */
+  include?: Array<'resource'>;
+}
+
+export interface ActionDismissParams {
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
+   */
+  include?: Array<'resource'>;
+}
+
+export declare namespace Actions {
+  export {
+    type ActionSeenParams as ActionSeenParams,
+    type ActionReadParams as ActionReadParams,
+    type ActionDismissParams as ActionDismissParams,
+  };
+}

package/src/resources/messaging/announcements/announcements.ts

@@ -0,0 +1,234 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as CoreAPI from '../../core/core';
+import * as APIKeysAPI from '../../auth/api-keys/api-keys';
+import * as ActionsAPI from './actions';
+import { ActionDismissParams, ActionReadParams, ActionSeenParams, Actions } from './actions';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * List, read, and manage broadcast announcements.
+ */
+export class Announcements extends APIResource {
+  actions: ActionsAPI.Actions = new ActionsAPI.Actions(this._client);
+
+  /**
+   * Returns the broadcast announcements currently active for the caller, most recent
+   * first.
+   *
+   * This endpoint requires the permission: `messaging:read`.
+   *
+   * @example
+   * ```ts
+   * const listAnnouncement =
+   *   await client.messaging.announcements.list();
+   * ```
+   */
+  list(
+    query: AnnouncementListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ListAnnouncement> {
+    return this._client.get('/v1/messaging/announcements', { query, ...options });
+  }
+
+  /**
+   * Returns one active announcement by ID.
+   *
+   * This endpoint requires the permission: `messaging:read`.
+   *
+   * @example
+   * ```ts
+   * const announcement =
+   *   await client.messaging.announcements.retrieve(
+   *     'an_01c4d5e6f7a8b9c0d1e2f3a4',
+   *   );
+   * ```
+   */
+  retrieve(
+    id: string,
+    query: AnnouncementRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Announcement> {
+    return this._client.get(path`/v1/messaging/announcements/${id}`, { query, ...options });
+  }
+}
+
+/**
+ * A broadcast announcement shown in the bell feed, with the caller's per-user read
+ * state.
+ */
+export interface Announcement {
+  /**
+   * Announcement ID.
+   */
+  id: string;
+
+  /**
+   * Preview/body text.
+   */
+  body: string | null;
+
+  /**
+   * Category of the announcement.
+   */
+  category:
+    | 'chat.message'
+    | 'chat.mention'
+    | 'chat.added'
+    | 'order.updated'
+    | 'agent.run_completed'
+    | 'agent.alert'
+    | 'system.broadcast';
+
+  /**
+   * Creation timestamp.
+   */
+  created_at: string;
+
+  /**
+   * When the calling actor dismissed the announcement.
+   */
+  dismissed_at: string | null;
+
+  /**
+   * When the announcement stops being shown.
+   */
+  expires_at: string | null;
+
+  /**
+   * Resource type identifier.
+   */
+  object: 'announcement';
+
+  /**
+   * Delivery priority.
+   */
+  priority: 'low' | 'normal' | 'high' | 'urgent';
+
+  /**
+   * When the announcement becomes visible in the feed.
+   */
+  publish_at: string;
+
+  /**
+   * When the calling actor opened the announcement.
+   */
+  read_at: string | null;
+
+  /**
+   * Entity is a polymorphic reference to any resource in the system.
+   */
+  resource: CoreAPI.Entity | null;
+
+  /**
+   * Reach of the announcement.
+   *
+   * - `account`: shown only to users within this account.
+   * - `platform`: shown to every user across all accounts.
+   */
+  scope: 'account' | 'platform';
+
+  /**
+   * When the calling actor first saw the announcement.
+   */
+  seen_at: string | null;
+
+  /**
+   * Lifecycle status of the announcement for the calling actor, derived from their
+   * seen/read/dismissed receipt.
+   *
+   * - `unseen`: not yet surfaced in the caller's feed.
+   * - `seen`: surfaced in the feed but not yet opened.
+   * - `read`: opened by the caller.
+   * - `dismissed`: dismissed by the caller.
+   */
+  status: 'unseen' | 'seen' | 'read' | 'dismissed';
+
+  /**
+   * Human-readable title.
+   */
+  title: string;
+
+  /**
+   * Last update timestamp.
+   */
+  updated_at: string;
+}
+
+/**
+ * List represents a paginated list of resources.
+ */
+export interface ListAnnouncement {
+  /**
+   * Resources in this page.
+   */
+  data: Array<Announcement>;
+
+  /**
+   * Resource type identifier.
+   */
+  object: 'list';
+
+  /**
+   * PageInfo contains URL-based pagination metadata.
+   */
+  page_info: APIKeysAPI.PageInfo;
+}
+
+export interface AnnouncementListParams {
+  /**
+   * Opaque cursor token identifying where the page of results starts.
+   *
+   * Use the `cursor` value embedded in a previous response's `next_page_url` or
+   * `previous_page_url` to fetch the adjacent page. Omit to start from the first
+   * page.
+   */
+  cursor?: string;
+
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
+   */
+  include?: Array<'resource'>;
+
+  /**
+   * Maximum number of results to return in a single page.
+   */
+  limit?: number;
+
+  /**
+   * Free-text search term used to filter results.
+   *
+   * Which fields are matched against the term varies by endpoint.
+   */
+  q?: string;
+}
+
+export interface AnnouncementRetrieveParams {
+  /**
+   * Sub-objects to expand in the response. When omitted, sub-objects are returned as
+   * `null`.
+   */
+  include?: Array<'resource'>;
+}
+
+Announcements.Actions = Actions;
+
+export declare namespace Announcements {
+  export {
+    type Announcement as Announcement,
+    type ListAnnouncement as ListAnnouncement,
+    type AnnouncementListParams as AnnouncementListParams,
+    type AnnouncementRetrieveParams as AnnouncementRetrieveParams,
+  };
+
+  export {
+    Actions as Actions,
+    type ActionSeenParams as ActionSeenParams,
+    type ActionReadParams as ActionReadParams,
+    type ActionDismissParams as ActionDismissParams,
+  };
+}

package/src/resources/messaging/announcements/index.ts

@@ -0,0 +1,10 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Actions, type ActionSeenParams, type ActionReadParams, type ActionDismissParams } from './actions';
+export {
+  Announcements,
+  type Announcement,
+  type ListAnnouncement,
+  type AnnouncementListParams,
+  type AnnouncementRetrieveParams,
+} from './announcements';

package/src/resources/messaging/announcements.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './announcements/index';