postgrid-node 0.5.0 → 0.6.1

package/src/resources/print-mail/postcards.ts

@@ -2,8 +2,6 @@
 
 import { APIResource } from '../../core/resource';
 import * as ContactsAPI from './contacts';
-import * as PrintMailAPI from './print-mail';
-import * as OrderProfilesPostcardsAPI from './order-profiles/postcards';
 import { APIPromise } from '../../core/api-promise';
 import { PagePromise, SkipLimit, type SkipLimitParams } from '../../core/pagination';
 import { RequestOptions } from '../../internal/request-options';
@@ -80,6 +78,41 @@ export class Postcards extends APIResource {
     return this._client.delete(path`/print-mail/v1/postcards/${id}`, options);
   }
 
+  /**
+   * Cancel a postcard by ID with a note. Note that this operation cannot be undone
+   * and that only postcards with a status of `ready` can be cancelled.
+   *
+   * @example
+   * ```ts
+   * const postcard = await client.printMail.postcards.cancel(
+   *   'id',
+   *   { note: 'Cancelling this postcard' },
+   * );
+   * ```
+   */
+  cancel(id: string, body: PostcardCancelParams, options?: RequestOptions): APIPromise<Postcard> {
+    return this._client.post(path`/print-mail/v1/postcards/${id}/cancellation`, { body, ...options });
+  }
+
+  /**
+   * Progresses a postcard's `status` to the next stage. This is only available in
+   * test mode and can be used to simulate how a live order would progress through
+   * the different statuses.
+   *
+   * Note: this will fail with an `invalid_progression_error` if the status is one of
+   * `completed` or `cancelled`.
+   *
+   * @example
+   * ```ts
+   * const postcard = await client.printMail.postcards.progress(
+   *   'id',
+   * );
+   * ```
+   */
+  progress(id: string, options?: RequestOptions): APIPromise<Postcard> {
+    return this._client.post(path`/print-mail/v1/postcards/${id}/progressions`, options);
+  }
+
   /**
    * Retrieve a postcard preview URL.
    *
@@ -164,7 +197,7 @@ export interface Postcard {
   /**
    * Enum representing the supported postcard sizes.
    */
-  size: OrderProfilesPostcardsAPI.PostcardSize;
+  size: '6x4' | '9x6' | '11x6';
 
   /**
    * See `OrderStatus` for more details on the status of this order.
@@ -230,6 +263,12 @@ export interface Postcard {
    */
   metadata?: { [key: string]: unknown };
 
+  /**
+   * Premium paper identifier. Use "standard" for regular stock or a premium*paper*\*
+   * ID.
+   */
+  paper?: string;
+
   /**
    * The tracking number of this order. Populated after an express/certified order
    * has been processed for delivery.
@@ -310,7 +349,7 @@ export declare namespace PostcardCreateParams {
     /**
      * Enum representing the supported postcard sizes.
      */
-    size: OrderProfilesPostcardsAPI.PostcardSize;
+    size: '6x4' | '9x6' | '11x6';
 
     /**
      * The recipient of this order. You can either supply the contact information
@@ -318,7 +357,7 @@ export declare namespace PostcardCreateParams {
      * contacts regardless of whether you provide the information inline here or call
      * the contact creation endpoint.
      */
-    to: PrintMailAPI.ContactCreateWithFirstName | PrintMailAPI.ContactCreateWithCompanyName | string;
+    to: ContactsAPI.ContactCreateWithFirstName | ContactsAPI.ContactCreateWithCompanyName | string;
 
     /**
      * An optional string describing this resource. Will be visible in the API and the
@@ -331,7 +370,7 @@ export declare namespace PostcardCreateParams {
      * here just like you can for the `to`. Unlike other order types, the sender
      * address is optional for postcards.
      */
-    from?: PrintMailAPI.ContactCreateWithFirstName | PrintMailAPI.ContactCreateWithCompanyName | string;
+    from?: ContactsAPI.ContactCreateWithFirstName | ContactsAPI.ContactCreateWithCompanyName | string;
 
     /**
      * The mailing class of this order. If not provided, automatically set to
@@ -378,6 +417,12 @@ export declare namespace PostcardCreateParams {
      */
     metadata?: { [key: string]: unknown };
 
+    /**
+     * Premium paper identifier. Use "standard" for regular stock or a premium*paper*\*
+     * ID.
+     */
+    paper?: string;
+
     /**
      * This order will transition from `ready` to `printing` on the day after this
      * date. You can use this parameter to schedule orders for a future date.
@@ -409,7 +454,7 @@ export declare namespace PostcardCreateParams {
     /**
      * Enum representing the supported postcard sizes.
      */
-    size: OrderProfilesPostcardsAPI.PostcardSize;
+    size: '6x4' | '9x6' | '11x6';
 
     /**
      * The recipient of this order. You can either supply the contact information
@@ -417,7 +462,7 @@ export declare namespace PostcardCreateParams {
      * contacts regardless of whether you provide the information inline here or call
      * the contact creation endpoint.
      */
-    to: PrintMailAPI.ContactCreateWithFirstName | PrintMailAPI.ContactCreateWithCompanyName | string;
+    to: ContactsAPI.ContactCreateWithFirstName | ContactsAPI.ContactCreateWithCompanyName | string;
 
     /**
      * An optional string describing this resource. Will be visible in the API and the
@@ -430,7 +475,7 @@ export declare namespace PostcardCreateParams {
      * here just like you can for the `to`. Unlike other order types, the sender
      * address is optional for postcards.
      */
-    from?: PrintMailAPI.ContactCreateWithFirstName | PrintMailAPI.ContactCreateWithCompanyName | string;
+    from?: ContactsAPI.ContactCreateWithFirstName | ContactsAPI.ContactCreateWithCompanyName | string;
 
     /**
      * The mailing class of this order. If not provided, automatically set to
@@ -477,6 +522,12 @@ export declare namespace PostcardCreateParams {
      */
     metadata?: { [key: string]: unknown };
 
+    /**
+     * Premium paper identifier. Use "standard" for regular stock or a premium*paper*\*
+     * ID.
+     */
+    paper?: string;
+
     /**
      * This order will transition from `ready` to `printing` on the day after this
      * date. You can use this parameter to schedule orders for a future date.
@@ -494,7 +545,7 @@ export declare namespace PostcardCreateParams {
     /**
      * Enum representing the supported postcard sizes.
      */
-    size: OrderProfilesPostcardsAPI.PostcardSize;
+    size: '6x4' | '9x6' | '11x6';
 
     /**
      * The recipient of this order. You can either supply the contact information
@@ -502,7 +553,7 @@ export declare namespace PostcardCreateParams {
      * contacts regardless of whether you provide the information inline here or call
      * the contact creation endpoint.
      */
-    to: PrintMailAPI.ContactCreateWithFirstName | PrintMailAPI.ContactCreateWithCompanyName | string;
+    to: ContactsAPI.ContactCreateWithFirstName | ContactsAPI.ContactCreateWithCompanyName | string;
 
     /**
      * An optional string describing this resource. Will be visible in the API and the
@@ -515,7 +566,7 @@ export declare namespace PostcardCreateParams {
      * here just like you can for the `to`. Unlike other order types, the sender
      * address is optional for postcards.
      */
-    from?: PrintMailAPI.ContactCreateWithFirstName | PrintMailAPI.ContactCreateWithCompanyName | string;
+    from?: ContactsAPI.ContactCreateWithFirstName | ContactsAPI.ContactCreateWithCompanyName | string;
 
     /**
      * The mailing class of this order. If not provided, automatically set to
@@ -562,6 +613,12 @@ export declare namespace PostcardCreateParams {
      */
     metadata?: { [key: string]: unknown };
 
+    /**
+     * Premium paper identifier. Use "standard" for regular stock or a premium*paper*\*
+     * ID.
+     */
+    paper?: string;
+
     /**
      * This order will transition from `ready` to `printing` on the day after this
      * date. You can use this parameter to schedule orders for a future date.
@@ -581,6 +638,10 @@ export interface PostcardListParams extends SkipLimitParams {
   search?: string;
 }
 
+export interface PostcardCancelParams {
+  note: string;
+}
+
 export declare namespace Postcards {
   export {
     type Postcard as Postcard,
@@ -588,5 +649,6 @@ export declare namespace Postcards {
     type PostcardsSkipLimit as PostcardsSkipLimit,
     type PostcardCreateParams as PostcardCreateParams,
     type PostcardListParams as PostcardListParams,
+    type PostcardCancelParams as PostcardCancelParams,
   };
 }