fix: address senior-dev audit findings (full @PARAM descs, auto-gen Roxy.php docs, drift checks, transport-error wrapping)

Author: ph33nx

.gitattributes

@@ -0,0 +1,17 @@
+# Mirror composer.json `archive.exclude` so `git archive` (and any tarball
+# generated outside Packagist's dist API) produces the same lean tree.
+
+/.github         export-ignore
+/.gitignore      export-ignore
+/.gitattributes  export-ignore
+/assets          export-ignore
+/composer.lock   export-ignore
+/examples        export-ignore
+/lefthook.yml    export-ignore
+/package.json    export-ignore
+/phpstan.neon    export-ignore
+/phpunit.xml     export-ignore
+/pint.json       export-ignore
+/scripts         export-ignore
+/specs           export-ignore
+/tests           export-ignore

.github/workflows/ci.yml

@@ -5,6 +5,9 @@ on:
   push:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -29,7 +32,7 @@ jobs:
         if: matrix.php == '8.2'
         run: |
           node scripts/generate.mjs
-          git diff --exit-code -- specs/openapi.json src/Generated tests/Generated src/Version.php \
+          git diff --exit-code -- specs/openapi.json src/Generated src/Roxy.php src/Version.php tests/Generated \
             || { echo 'codegen drift: commit the regenerated files'; exit 1; }
 
       - name: Lint

lefthook.yml

@@ -22,7 +22,7 @@ pre-push:
       run: vendor/bin/phpstan analyse --no-progress --memory-limit=1G
       priority: 2
     codegen-drift:
-      run: node scripts/generate.mjs && git diff --exit-code -- specs/openapi.json src/Generated src/Version.php || { echo 'codegen drift: commit the regenerated files'; exit 1; }
+      run: node scripts/generate.mjs && git diff --exit-code -- specs/openapi.json src/Generated src/Roxy.php src/Version.php tests/Generated || { echo 'codegen drift: commit the regenerated files'; exit 1; }
       priority: 3
     docs-drift:
       run: node scripts/sync-docs.mjs && git diff --exit-code -- README.md AGENTS.md || { echo 'docs drift: commit the regenerated README.md/AGENTS.md'; exit 1; }

scripts/generate.mjs

@@ -26,7 +26,6 @@ const SPEC_FILE = path.join(ROOT, 'specs', 'openapi.json');
 const OUT_DIR = path.join(ROOT, 'src', 'Generated');
 const RESOURCES_DIR = path.join(OUT_DIR, 'Resources');
 const REQUESTS_DIR = path.join(OUT_DIR, 'Requests');
-const DTO_DIR = path.join(OUT_DIR, 'Dto');
 const VERSION_FILE = path.join(ROOT, 'src', 'Version.php');
 const ROXY_FILE = path.join(ROOT, 'src', 'Roxy.php');
 const TESTS_GENERATED_DIR = path.join(ROOT, 'tests', 'Generated');
@@ -496,8 +495,14 @@ function emitResource(tagName, ops) {
 		docLines.push(`     * ${op.method} ${op.path}`);
 		docLines.push('     *');
 		for (const p of params) {
-			const desc = p.description ? ' ' + p.description.replace(/\s+/g, ' ').slice(0, 90) : '';
-			docLines.push(`     * @param ${p.required ? p.type : p.type + '|null'} \$${p.name}${desc}`);
+			const flat = p.description ? p.description.replace(/\s+/g, ' ').trim() : '';
+			if (flat) {
+				const wrapped = wrapDoc(flat, '     *   ');
+				docLines.push(`     * @param ${p.required ? p.type : p.type + '|null'} \$${p.name}`);
+				docLines.push(...wrapped);
+			} else {
+				docLines.push(`     * @param ${p.required ? p.type : p.type + '|null'} \$${p.name}`);
+			}
 		}
 		docLines.push('     *');
 		docLines.push('     * @return array<string, mixed>');
@@ -539,13 +544,15 @@ const BASE_RESOURCE = `${HEADER}
 namespace RoxyAPI\\Sdk\\Generated\\Resources;
 
 use RoxyAPI\\Sdk\\RoxyApiException;
+use Saloon\\Exceptions\\Request\\FatalRequestException;
 use Saloon\\Http\\BaseResource as SaloonBaseResource;
 use Saloon\\Http\\Request;
 
 /**
  * Shared base for every generated Resource class. Sends a Saloon Request,
- * decodes the JSON body, and throws RoxyApiException on 4xx/5xx so callers
- * never have to inspect HTTP status codes.
+ * decodes the JSON body, and throws RoxyApiException for everything callers
+ * should care about (4xx, 5xx, and transport failures) so consumers never
+ * have to catch more than one exception type.
  */
 abstract class BaseResource extends SaloonBaseResource
 {
@@ -554,15 +561,23 @@ abstract class BaseResource extends SaloonBaseResource
      */
     protected function callRequest(Request $request): array
     {
-        $response = $this->connector->send($request);
+        try {
+            $response = $this->connector->send($request);
+        } catch (FatalRequestException $e) {
+            throw RoxyApiException::fromFatal($e);
+        }
 
         if ($response->failed()) {
             throw RoxyApiException::fromResponse($response);
         }
 
-        $decoded = $response->json();
+        try {
+            $decoded = $response->json();
+        } catch (\\Throwable) {
+            $decoded = null;
+        }
 
-        return is_array($decoded) ? $decoded : ['data' => $decoded];
+        return is_array($decoded) ? $decoded : [];
     }
 }
 `;
@@ -632,11 +647,10 @@ it('${namespace} resource sends ${sample.operationId} and parses JSON', function
 // Clean generated dirs first so deletions in the spec actually remove files.
 await fs.rm(RESOURCES_DIR, { recursive: true, force: true });
 await fs.rm(REQUESTS_DIR, { recursive: true, force: true });
-await fs.rm(DTO_DIR, { recursive: true, force: true });
+await fs.rm(path.join(OUT_DIR, 'Dto'), { recursive: true, force: true });
 await fs.rm(TESTS_GENERATED_DIR, { recursive: true, force: true });
 await fs.mkdir(RESOURCES_DIR, { recursive: true });
 await fs.mkdir(REQUESTS_DIR, { recursive: true });
-await fs.mkdir(DTO_DIR, { recursive: true });
 await fs.mkdir(TESTS_GENERATED_DIR, { recursive: true });
 
 // BaseResource (committed once, never changes per spec — but emit every time
@@ -658,13 +672,6 @@ for (const op of operations) {
 	await fs.writeFile(file, emitRequest(op), 'utf8');
 }
 
-// Placeholder so the empty Dto dir survives codegen and the package ships consistently.
-await fs.writeFile(
-	path.join(DTO_DIR, '.gitkeep'),
-	'# Reserved for future typed response DTOs. Methods currently return array<string, mixed>.\n',
-	'utf8',
-);
-
 // Per-tag smoke tests
 for (const tag of Object.keys(opsByTag).sort()) {
 	const file = path.join(TESTS_GENERATED_DIR, tagToClassName(tag) + 'Test.php');

src/Generated/Dto/.gitkeep

@@ -29,8 +29,13 @@ class AngelNumbersResource extends BaseResource
      *
      * GET /angel-numbers/lookup
      *
-     * @param string $number Number sequence to analyze (1-8 digits). Can be any number the user has encountered: clock
-     * @param string|null $lang Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. 
+     * @param string $number
+     *   Number sequence to analyze (1-8 digits). Can be any number the user has encountered: clock
+     *   times (1111), addresses (717), receipts (888), license plates (4444), or any repeating
+     *   pattern.
+     * @param string|null $lang
+     *   Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en.
+     *   Languages without translations yet return English.
      *
      * @return array<string, mixed>
      */
@@ -55,8 +60,12 @@ public function analyzeNumberSequence(
      *
      * GET /angel-numbers/numbers/{number}
      *
-     * @param string $number Angel number sequence to look up (e.g., "111", "444", "1212", "1234"). Must match an entry
-     * @param string|null $lang Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. 
+     * @param string $number
+     *   Angel number sequence to look up (e.g., "111", "444", "1212", "1234"). Must match an entry
+     *   in the database.
+     * @param string|null $lang
+     *   Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en.
+     *   Languages without translations yet return English.
      *
      * @return array<string, mixed>
      */
@@ -81,9 +90,16 @@ public function getAngelNumber(
      *
      * POST /angel-numbers/daily
      *
-     * @param string|null $date Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing pas
-     * @param string|null $seed Optional seed for reproducible readings. Same seed + same date = same angel number every t
-     * @param string|null $lang Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. 
+     * @param string|null $date
+     *   Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past
+     *   daily readings or pre-generating future ones.
+     * @param string|null $seed
+     *   Optional seed for reproducible readings. Same seed + same date = same angel number every
+     *   time. Pass any unique identifier (userId, email hash, session token). Omit for anonymous
+     *   daily readings.
+     * @param string|null $lang
+     *   Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en.
+     *   Languages without translations yet return English.
      *
      * @return array<string, mixed>
      */
@@ -109,10 +125,17 @@ public function getDailyAngelNumber(
      *
      * GET /angel-numbers/numbers
      *
-     * @param string|null $lang Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. 
-     * @param int|null $limit Maximum items to return per page. Range: 1-50, default 20.
-     * @param int|null $offset Number of items to skip for pagination. Default 0.
-     * @param string|null $type Filter results by angel number pattern type. "repeating" returns numbers like 111, 444, 77
+     * @param string|null $lang
+     *   Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en.
+     *   Languages without translations yet return English.
+     * @param int|null $limit
+     *   Maximum items to return per page. Range: 1-50, default 20.
+     * @param int|null $offset
+     *   Number of items to skip for pagination. Default 0.
+     * @param string|null $type
+     *   Filter results by angel number pattern type. "repeating" returns numbers like 111, 444,
+     *   7777. "sequential" returns patterns like 1234. "mirror" returns palindrome patterns like
+     *   1212. "master" returns 11, 22, 33. "root" returns single digits 0-9.
      *
      * @return array<string, mixed>
      */