feat(api): api update

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 21
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/cas-parser%2Fcas-parser-d868ff00b7b07f6b6802b00f22fad531a91a76bb219a634f3f90fe488bd499ba.yml
-openapi_spec_hash: 20e9f2fc31feee78878cdf56e46dab60
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/cas-parser%2Fcas-parser-78ef474b9e171a3eaa430a9dacdc2fa5c7f7d5f89147cb20573a355d3dbb9f0e.yml
+openapi_spec_hash: 11b6e43ef4ed724f9804c9d790a4faee
 config_hash: 5509bb7a961ae2e79114b24c381606d4

src/InboundEmail/InboundEmailCreateParams.php

@@ -5,34 +5,27 @@
 namespace CasParser\InboundEmail;
 
 use CasParser\Core\Attributes\Optional;
-use CasParser\Core\Attributes\Required;
 use CasParser\Core\Concerns\SdkModel;
 use CasParser\Core\Concerns\SdkParams;
 use CasParser\Core\Contracts\BaseModel;
 use CasParser\InboundEmail\InboundEmailCreateParams\AllowedSource;
 
 /**
- * Create a dedicated inbound email address for collecting CAS statements via email forwarding.
+ * Create a dedicated inbound email address for collecting CAS statements
+ * via email forwarding. When an investor forwards a CAS email to this
+ * address, we verify the sender and make the file available to you.
  *
- * **How it works:**
- * 1. Create an inbound email with your webhook URL
- * 2. Display the email address to your user (e.g., "Forward your CAS to ie_xxx@import.casparser.in")
- * 3. When an investor forwards a CAS email, we verify the sender and deliver to your webhook
- *
- * **Webhook Delivery:**
- * - We POST to your `callback_url` with JSON body containing files (matching EmailCASFile schema)
- * - Failed deliveries are retried automatically with exponential backoff
- *
- * **Inactivity:**
- * - Inbound emails with no activity in 30 days are marked inactive
- * - Active inbound emails remain operational indefinitely
+ * `callback_url` is **optional**:
+ * - **Set it** — we POST each parsed email to your webhook as it arrives.
+ * - **Omit it** — retrieve files via `GET /v4/inbound-email/{id}/files`
+ *   without building a webhook consumer.
  *
  * @see CasParser\Services\InboundEmailService::create()
  *
  * @phpstan-type InboundEmailCreateParamsShape = array{
- *   callbackURL: string,
  *   alias?: string|null,
  *   allowedSources?: list<AllowedSource|value-of<AllowedSource>>|null,
+ *   callbackURL?: string|null,
  *   metadata?: array<string,string>|null,
  *   reference?: string|null,
  * }
@@ -44,19 +37,10 @@ final class InboundEmailCreateParams implements BaseModel
     use SdkParams;
 
     /**
-     * Webhook URL where we POST email notifications.
-     * Must be HTTPS in production (HTTP allowed for localhost during development).
-     */
-    #[Required('callback_url')]
-    public string $callbackURL;
-
-    /**
-     * Optional custom email prefix for user-friendly addresses.
-     * - Must be 3-32 characters
-     * - Alphanumeric + hyphens only
-     * - Must start and end with letter/number
-     * - Example: `john-portfolio@import.casparser.in`
-     * - If omitted, generates random ID like `ie_abc123xyz@import.casparser.in`.
+     * Optional custom email prefix (e.g.
+     * `john-portfolio@import.casparser.in`). 3-32 chars,
+     * alphanumeric + hyphens, must start/end with a letter or
+     * number. If omitted, a random ID is generated.
      */
     #[Optional]
     public ?string $alias;
@@ -73,6 +57,14 @@ final class InboundEmailCreateParams implements BaseModel
     #[Optional('allowed_sources', list: AllowedSource::class)]
     public ?array $allowedSources;
 
+    /**
+     * Optional webhook URL where we POST parsed emails. Must be
+     * HTTPS in production (HTTP allowed for localhost). If omitted,
+     * retrieve files via `GET /v4/inbound-email/{id}/files`.
+     */
+    #[Optional('callback_url', nullable: true)]
+    public ?string $callbackURL;
+
     /**
      * Optional key-value pairs (max 10) to include in webhook payload.
      * Useful for passing context like plan_type, campaign_id, etc.
@@ -89,20 +81,6 @@ final class InboundEmailCreateParams implements BaseModel
     #[Optional]
     public ?string $reference;
 
-    /**
-     * `new InboundEmailCreateParams()` is missing required properties by the API.
-     *
-     * To enforce required parameters use
-     * ```
-     * InboundEmailCreateParams::with(callbackURL: ...)
-     * ```
-     *
-     * Otherwise ensure the following setters are called
-     *
-     * ```
-     * (new InboundEmailCreateParams)->withCallbackURL(...)
-     * ```
-     */
     public function __construct()
     {
         $this->initialize();
@@ -117,43 +95,28 @@ public function __construct()
      * @param array<string,string>|null $metadata
      */
     public static function with(
-        string $callbackURL,
         ?string $alias = null,
         ?array $allowedSources = null,
+        ?string $callbackURL = null,
         ?array $metadata = null,
         ?string $reference = null,
     ): self {
         $self = new self;
 
-        $self['callbackURL'] = $callbackURL;
-
         null !== $alias && $self['alias'] = $alias;
         null !== $allowedSources && $self['allowedSources'] = $allowedSources;
+        null !== $callbackURL && $self['callbackURL'] = $callbackURL;
         null !== $metadata && $self['metadata'] = $metadata;
         null !== $reference && $self['reference'] = $reference;
 
         return $self;
     }
 
     /**
-     * Webhook URL where we POST email notifications.
-     * Must be HTTPS in production (HTTP allowed for localhost during development).
-     */
-    public function withCallbackURL(string $callbackURL): self
-    {
-        $self = clone $this;
-        $self['callbackURL'] = $callbackURL;
-
-        return $self;
-    }
-
-    /**
-     * Optional custom email prefix for user-friendly addresses.
-     * - Must be 3-32 characters
-     * - Alphanumeric + hyphens only
-     * - Must start and end with letter/number
-     * - Example: `john-portfolio@import.casparser.in`
-     * - If omitted, generates random ID like `ie_abc123xyz@import.casparser.in`.
+     * Optional custom email prefix (e.g.
+     * `john-portfolio@import.casparser.in`). 3-32 chars,
+     * alphanumeric + hyphens, must start/end with a letter or
+     * number. If omitted, a random ID is generated.
      */
     public function withAlias(string $alias): self
     {
@@ -180,6 +143,19 @@ public function withAllowedSources(array $allowedSources): self
         return $self;
     }
 
+    /**
+     * Optional webhook URL where we POST parsed emails. Must be
+     * HTTPS in production (HTTP allowed for localhost). If omitted,
+     * retrieve files via `GET /v4/inbound-email/{id}/files`.
+     */
+    public function withCallbackURL(?string $callbackURL): self
+    {
+        $self = clone $this;
+        $self['callbackURL'] = $callbackURL;
+
+        return $self;
+    }
+
     /**
      * Optional key-value pairs (max 10) to include in webhook payload.
      * Useful for passing context like plan_type, campaign_id, etc.

src/InboundEmail/InboundEmailGetResponse.php

@@ -39,9 +39,10 @@ final class InboundEmailGetResponse implements BaseModel
     public ?array $allowedSources;
 
     /**
-     * Webhook URL for email notifications.
+     * Webhook URL for email notifications. `null` means files are only
+     * retrievable via `GET /v4/inbound-email/{id}/files` (pull delivery).
      */
-    #[Optional('callback_url')]
+    #[Optional('callback_url', nullable: true)]
     public ?string $callbackURL;
 
     /**
@@ -144,9 +145,10 @@ public function withAllowedSources(array $allowedSources): self
     }
 
     /**
-     * Webhook URL for email notifications.
+     * Webhook URL for email notifications. `null` means files are only
+     * retrievable via `GET /v4/inbound-email/{id}/files` (pull delivery).
      */
-    public function withCallbackURL(string $callbackURL): self
+    public function withCallbackURL(?string $callbackURL): self
     {
         $self = clone $this;
         $self['callbackURL'] = $callbackURL;

src/InboundEmail/InboundEmailListResponse/InboundEmail.php

@@ -39,9 +39,10 @@ final class InboundEmail implements BaseModel
     public ?array $allowedSources;
 
     /**
-     * Webhook URL for email notifications.
+     * Webhook URL for email notifications. `null` means files are only
+     * retrievable via `GET /v4/inbound-email/{id}/files` (pull delivery).
      */
-    #[Optional('callback_url')]
+    #[Optional('callback_url', nullable: true)]
     public ?string $callbackURL;
 
     /**
@@ -144,9 +145,10 @@ public function withAllowedSources(array $allowedSources): self
     }
 
     /**
-     * Webhook URL for email notifications.
+     * Webhook URL for email notifications. `null` means files are only
+     * retrievable via `GET /v4/inbound-email/{id}/files` (pull delivery).
      */
-    public function withCallbackURL(string $callbackURL): self
+    public function withCallbackURL(?string $callbackURL): self
     {
         $self = clone $this;
         $self['callbackURL'] = $callbackURL;

src/InboundEmail/InboundEmailNewResponse.php

@@ -39,9 +39,10 @@ final class InboundEmailNewResponse implements BaseModel
     public ?array $allowedSources;
 
     /**
-     * Webhook URL for email notifications.
+     * Webhook URL for email notifications. `null` means files are only
+     * retrievable via `GET /v4/inbound-email/{id}/files` (pull delivery).
      */
-    #[Optional('callback_url')]
+    #[Optional('callback_url', nullable: true)]
     public ?string $callbackURL;
 
     /**
@@ -144,9 +145,10 @@ public function withAllowedSources(array $allowedSources): self
     }
 
     /**
-     * Webhook URL for email notifications.
+     * Webhook URL for email notifications. `null` means files are only
+     * retrievable via `GET /v4/inbound-email/{id}/files` (pull delivery).
      */
-    public function withCallbackURL(string $callbackURL): self
+    public function withCallbackURL(?string $callbackURL): self
     {
         $self = clone $this;
         $self['callbackURL'] = $callbackURL;

src/ServiceContracts/InboundEmailContract.php

@@ -21,19 +21,18 @@ interface InboundEmailContract
     /**
      * @api
      *
-     * @param string $callbackURL Webhook URL where we POST email notifications.
-     * Must be HTTPS in production (HTTP allowed for localhost during development).
-     * @param string $alias Optional custom email prefix for user-friendly addresses.
-     * - Must be 3-32 characters
-     * - Alphanumeric + hyphens only
-     * - Must start and end with letter/number
-     * - Example: `john-portfolio@import.casparser.in`
-     * - If omitted, generates random ID like `ie_abc123xyz@import.casparser.in`
+     * @param string $alias Optional custom email prefix (e.g.
+     * `john-portfolio@import.casparser.in`). 3-32 chars,
+     * alphanumeric + hyphens, must start/end with a letter or
+     * number. If omitted, a random ID is generated.
      * @param list<AllowedSource|value-of<AllowedSource>> $allowedSources Filter emails by CAS provider. If omitted, accepts all providers.
      * - `cdsl` → eCAS@cdslstatement.com
      * - `nsdl` → NSDL-CAS@nsdl.co.in
      * - `cams` → donotreply@camsonline.com
      * - `kfintech` → samfS@kfintech.com
+     * @param string|null $callbackURL Optional webhook URL where we POST parsed emails. Must be
+     * HTTPS in production (HTTP allowed for localhost). If omitted,
+     * retrieve files via `GET /v4/inbound-email/{id}/files`.
      * @param array<string,string> $metadata Optional key-value pairs (max 10) to include in webhook payload.
      * Useful for passing context like plan_type, campaign_id, etc.
      * @param string $reference Your internal identifier (e.g., user_id, account_id).
@@ -43,9 +42,9 @@ interface InboundEmailContract
      * @throws APIException
      */
     public function create(
-        string $callbackURL,
         ?string $alias = null,
         ?array $allowedSources = null,
+        ?string $callbackURL = null,
         ?array $metadata = null,
         ?string $reference = null,
         RequestOptions|array|null $requestOptions = null,

src/Services/InboundEmailRawService.php

@@ -53,25 +53,19 @@ public function __construct(private Client $client) {}
     /**
      * @api
      *
-     * Create a dedicated inbound email address for collecting CAS statements via email forwarding.
+     * Create a dedicated inbound email address for collecting CAS statements
+     * via email forwarding. When an investor forwards a CAS email to this
+     * address, we verify the sender and make the file available to you.
      *
-     * **How it works:**
-     * 1. Create an inbound email with your webhook URL
-     * 2. Display the email address to your user (e.g., "Forward your CAS to ie_xxx@import.casparser.in")
-     * 3. When an investor forwards a CAS email, we verify the sender and deliver to your webhook
-     *
-     * **Webhook Delivery:**
-     * - We POST to your `callback_url` with JSON body containing files (matching EmailCASFile schema)
-     * - Failed deliveries are retried automatically with exponential backoff
-     *
-     * **Inactivity:**
-     * - Inbound emails with no activity in 30 days are marked inactive
-     * - Active inbound emails remain operational indefinitely
+     * `callback_url` is **optional**:
+     * - **Set it** — we POST each parsed email to your webhook as it arrives.
+     * - **Omit it** — retrieve files via `GET /v4/inbound-email/{id}/files`
+     *   without building a webhook consumer.
      *
      * @param array{
-     *   callbackURL: string,
      *   alias?: string,
      *   allowedSources?: list<AllowedSource|value-of<AllowedSource>>,
+     *   callbackURL?: string|null,
      *   metadata?: array<string,string>,
      *   reference?: string,
      * }|InboundEmailCreateParams $params