دليل الربط عبر واجهة Udeyou OTP

#!/usr/bin/env bash

# Send a verification code by email.

# Usage: UDEYOU_API_KEY=udy_test_... ./send.sh user@example.com

BASE_URL="${UDEYOU_BASE_URL:-https://udeyou.com/api/v1}"

TO="${1:-user@example.com}"



curl -sS --max-time 20 -X POST "$BASE_URL/otp/send" \

  -H "Authorization: Bearer $UDEYOU_API_KEY" \

  -H "Content-Type: application/json" \

  -d '{"to": "'"$TO"'", "lang": "ar"}'

echo

#!/usr/bin/env bash

# Verify the code the user entered.

# Usage: UDEYOU_API_KEY=udy_test_... ./verify.sh otp_xxxxxxxx 123456

BASE_URL="${UDEYOU_BASE_URL:-https://udeyou.com/api/v1}"



curl -sS --max-time 20 -X POST "$BASE_URL/otp/verify" \

  -H "Authorization: Bearer $UDEYOU_API_KEY" \

  -H "Content-Type: application/json" \

  -d '{"otp_id": "'"$1"'", "code": "'"$2"'"}'

echo

#!/usr/bin/env bash

# Current credit balance for the account that owns the key.

BASE_URL="${UDEYOU_BASE_URL:-https://udeyou.com/api/v1}"



curl -sS --max-time 20 "$BASE_URL/balance" \

  -H "Authorization: Bearer $UDEYOU_API_KEY"

echo

// config/services.php: add this entry to the returned array

'udeyou' => [

    'key' => env('UDEYOU_API_KEY'), // .env: UDEYOU_API_KEY=udy_test_...

    'url' => env('UDEYOU_BASE_URL', 'https://udeyou.com/api/v1'),

],

<?php



namespace App\Services;



use Illuminate\Http\Client\PendingRequest;

use Illuminate\Http\Client\Response;

use Illuminate\Support\Facades\Http;



// Udeyou OTP client for Laravel 10+ (HTTP client). The key stays in .env on the server.

class Udeyou

{

    /** POST /otp/send. data: otp_id, to, expires_in, expires_at, credits_remaining (+ code with a test key). */

    public function send(string $to, array $options = []): Response

    {

        return $this->http()->post('/otp/send', ['to' => $to] + $options + ['lang' => 'ar']);

    }



    /** POST /otp/verify. data: verified, otp_id, to, verified_at. */

    public function verify(string $otpId, string $code): Response

    {

        return $this->http()->post('/otp/verify', ['otp_id' => $otpId, 'code' => $code]);

    }



    /** GET /balance. data: company, mode, credits. */

    public function balance(): Response

    {

        return $this->http()->get('/balance');

    }



    private function http(): PendingRequest

    {

        return Http::baseUrl(config('services.udeyou.url'))

            ->withToken(config('services.udeyou.key'))

            ->acceptJson()

            ->timeout(20);

    }

}

<?php



namespace App\Http\Controllers;



use App\Services\Udeyou;

use Illuminate\Http\Client\ConnectionException;

use Illuminate\Http\Client\Response;

use Illuminate\Http\RedirectResponse;

use Illuminate\Http\Request;



class OtpController extends Controller

{

    public function __construct(private Udeyou $udeyou) {}



    // POST /otp/send  (email)

    public function send(Request $request): RedirectResponse

    {

        $data = $request->validate(['email' => ['required', 'email', 'max:190']]);



        try {

            $res = $this->udeyou->send($data['email']);

        } catch (ConnectionException) {

            return back()->withInput()->withErrors(['email' => 'The service is unavailable. Try again later.']);

        }

        if ($res->failed()) {

            return back()->withInput()->withErrors(['email' => $this->message($res)]);

        }



        // Keep otp_id in the server session, never in a hidden form field.

        $request->session()->put('otp_id', $res->json('data.otp_id'));



        return back()->with('status', 'We sent a code to your email.');

    }



    // POST /otp/verify  (code)

    public function verify(Request $request): RedirectResponse

    {

        $data = $request->validate(['code' => ['required', 'string', 'regex:/^[0-9A-Za-z]{4,10}$/']]);

        $otpId = $request->session()->get('otp_id');

        if (! $otpId) {

            return back()->withErrors(['code' => 'Request a code first.']);

        }



        try {

            $res = $this->udeyou->verify($otpId, $data['code']);

        } catch (ConnectionException) {

            return back()->withErrors(['code' => 'The service is unavailable. Try again later.']);

        }

        if ($res->failed()) {

            return back()->withErrors(['code' => $this->message($res)]);

        }



        $request->session()->forget('otp_id');

        // data.to is the verified address: sign the user in or mark the email as verified here.

        $request->session()->put('verified_email', $res->json('data.to'));



        return redirect()->intended('/');

    }



    private function message(Response $res): string

    {

        return match ($res->json('error.code')) {

            'invalid_code' => 'Incorrect code. Attempts left: '.$res->json('error.attempts_remaining'),

            'resend_too_soon', 'recipient_limit', 'rate_limited' => 'Please wait '.$res->json('error.retry_after').' seconds and try again.',

            'otp_expired', 'otp_already_used', 'otp_not_found', 'too_many_attempts' => 'This code is no longer valid. Request a new one.',

            'validation_error' => 'Check the email address and try again.',

            // 401, 402, 403 and 5xx: log $res->json('error') and show a generic message.

            default => 'The service is unavailable. Try again later.',

        };

    }

}

// routes/web.php (Route is already imported at the top of this file)

use App\Http\Controllers\OtpController;



Route::view('/otp', 'otp');

Route::post('/otp/send', [OtpController::class, 'send'])->middleware('throttle:5,1');

Route::post('/otp/verify', [OtpController::class, 'verify'])->middleware('throttle:10,1');

{{-- resources/views/otp.blade.php --}}

@if (session('status'))

    <p>{{ session('status') }}</p>

@endif



<form method="POST" action="/otp/send">

    @csrf

    <input type="email" name="email" value="{{ old('email') }}" autocomplete="email" required>

    <button type="submit">Send code</button>

    @error('email') <p>{{ $message }}</p> @enderror

</form>



@if (session('otp_id'))

    <form method="POST" action="/otp/verify">

        @csrf

        <input name="code" inputmode="numeric" autocomplete="one-time-code" required>

        <button type="submit">Verify</button>

        @error('code') <p>{{ $message }}</p> @enderror

    </form>

@endif

name: otp_backend

description: Udeyou OTP client and a sample shelf backend for Flutter apps.

publish_to: none



environment:

  sdk: ^3.0.0



dependencies:

  http: ^1.2.0

  shelf: ^1.4.0

  shelf_router: ^1.1.0



dev_dependencies:

  lints: ^5.0.0

// Udeyou OTP client for Dart servers (package:http).

// Keep the API key on the server. Never ship it inside a mobile or web app.

import 'dart:async';

import 'dart:convert';



import 'package:http/http.dart' as http;



class UdeyouException implements Exception {

  UdeyouException(this.statusCode, this.code, this.message, [this.details = const {}]);



  final int statusCode;

  final String code;

  final String message;



  /// Extra fields such as retry_after, attempts_remaining or fields.

  final Map<String, dynamic> details;



  int? get retryAfter => details['retry_after'] as int?;

  int? get attemptsRemaining => details['attempts_remaining'] as int?;



  @override

  String toString() => 'UdeyouException($statusCode $code: $message)';

}



class UdeyouClient {

  UdeyouClient({

    required this.apiKey,

    this.baseUrl = 'https://udeyou.com/api/v1',

    http.Client? httpClient,

  }) : _http = httpClient ?? http.Client();



  final String apiKey;

  final String baseUrl;

  final http.Client _http;



  static const _timeout = Duration(seconds: 20);



  /// Sends a code to [to]. Returns otp_id, expires_in, expires_at, credits_remaining

  /// (and code when using a udy_test_ key).

  Future<Map<String, dynamic>> sendOtp(

    String to, {

    String lang = 'ar',

    String? senderName,

    int? codeLength,

    int? expiresIn,

  }) {

    return _request('POST', '/otp/send', {

      'to': to,

      'lang': lang,

      if (senderName != null) 'sender_name': senderName,

      if (codeLength != null) 'code_length': codeLength,

      if (expiresIn != null) 'expires_in': expiresIn,

    });

  }



  /// Verifies [code]. Returns verified, otp_id, to and verified_at.

  Future<Map<String, dynamic>> verifyOtp({required String otpId, required String code}) {

    return _request('POST', '/otp/verify', {'otp_id': otpId, 'code': code});

  }



  /// Returns company, mode and credits.

  Future<Map<String, dynamic>> balance() => _request('GET', '/balance');



  void close() => _http.close();



  Future<Map<String, dynamic>> _request(String method, String path,

      [Map<String, Object>? body]) async {

    final uri = Uri.parse('$baseUrl$path');

    final headers = {

      'Authorization': 'Bearer $apiKey',

      'Content-Type': 'application/json',

      'Accept': 'application/json',

    };



    final http.Response res;

    try {

      res = await (method == 'GET'

              ? _http.get(uri, headers: headers)

              : _http.post(uri, headers: headers, body: jsonEncode(body)))

          .timeout(_timeout);

    } on TimeoutException {

      throw UdeyouException(0, 'timeout', 'No response within ${_timeout.inSeconds} s');

    }



    Map<String, dynamic> json;

    try {

      json = jsonDecode(res.body) as Map<String, dynamic>;

    } on FormatException {

      json = const {};

    }



    if (res.statusCode >= 400 || json['success'] != true) {

      final error = Map<String, dynamic>.from(json['error'] as Map? ?? const {});

      throw UdeyouException(

        res.statusCode,

        error.remove('code') as String? ?? 'http_${res.statusCode}',

        error.remove('message') as String? ?? 'Unexpected response',

        error,

      );

    }

    return json['data'] as Map<String, dynamic>;

  }

}

// Usage: UDEYOU_API_KEY=udy_test_... dart run bin/demo.dart user@example.com

import 'dart:io';



import 'package:otp_backend/udeyou_client.dart';



Future<void> main(List<String> args) async {

  final env = Platform.environment;

  final udeyou = UdeyouClient(

    apiKey: env['UDEYOU_API_KEY'] ?? '',

    baseUrl: env['UDEYOU_BASE_URL'] ?? 'https://udeyou.com/api/v1',

  );

  final to = args.isNotEmpty ? args.first : 'user@example.com';



  try {

    // 1) Send the code

    final sent = await udeyou.sendOtp(to);

    print('Sent ${sent['otp_id']} to ${sent['to']} (expires in ${sent['expires_in']} s)');



    // 2) Verify the code the user typed. Test keys (udy_test_) return it in the response.

    var code = sent['code'] as String?;

    if (code == null) {

      stdout.write('Code: ');

      code = stdin.readLineSync()?.trim() ?? '';

    }

    final result = await udeyou.verifyOtp(otpId: sent['otp_id'] as String, code: code);

    print('Verified ${result['to']} at ${result['verified_at']}');

  } on UdeyouException catch (e) {

    stderr.writeln('Error ${e.statusCode} ${e.code}: ${e.message}');

    if (e.details.isNotEmpty) stderr.writeln(e.details);

    exitCode = 1;

  } finally {

    udeyou.close();

  }

}

// Your backend: the Flutter app calls these routes, and only this server holds the Udeyou key.

// Usage: UDEYOU_API_KEY=udy_live_... dart run bin/server.dart

import 'dart:convert';

import 'dart:io';



import 'package:otp_backend/udeyou_client.dart';

import 'package:shelf/shelf.dart';

import 'package:shelf/shelf_io.dart' as io;

import 'package:shelf_router/shelf_router.dart';



final udeyou = UdeyouClient(

  apiKey: Platform.environment['UDEYOU_API_KEY']!,

  baseUrl: Platform.environment['UDEYOU_BASE_URL'] ?? 'https://udeyou.com/api/v1',

);



Future<void> main() async {

  final router = Router()

    // {email} -> {otp_id, expires_in}

    ..post('/auth/otp/send', (Request req) async {

      final body = await _readJson(req);

      final sent = await udeyou.sendOtp('${body['email'] ?? ''}'.trim());

      return _json(200, {'otp_id': sent['otp_id'], 'expires_in': sent['expires_in']});

    })

    // {otp_id, code} -> {verified}

    ..post('/auth/otp/verify', (Request req) async {

      final body = await _readJson(req);

      final result = await udeyou.verifyOtp(

        otpId: '${body['otp_id'] ?? ''}',

        code: '${body['code'] ?? ''}',

      );

      // result['to'] is the verified email: sign the user in or mark the address as verified here.

      return _json(200, {'verified': result['verified'] == true});

    });



  final handler = const Pipeline().addMiddleware(_errors()).addHandler(router.call);

  final server = await io.serve(

      handler, InternetAddress.anyIPv4, int.parse(Platform.environment['PORT'] ?? '8081'));

  print('Listening on http://${server.address.host}:${server.port}');

}



Future<Map<String, dynamic>> _readJson(Request req) async {

  final decoded = jsonDecode(await req.readAsString());

  if (decoded is Map<String, dynamic>) return decoded;

  throw const FormatException('Expected a JSON object');

}



Response _json(int status, Map<String, Object?> body) =>

    Response(status, body: jsonEncode(body), headers: {'Content-Type': 'application/json'});



Middleware _errors() => (inner) => (req) async {

      try {

        return await inner(req);

      } on FormatException {

        return _json(400, {'error': 'invalid_json', 'message': 'Send a JSON object.'});

      } on UdeyouException catch (e) {

        // A bad key, an empty balance or an outage is our problem: log it, do not expose it.

        if (e.statusCode == 0 ||

            e.statusCode >= 500 ||

            const {401, 402, 403}.contains(e.statusCode)) {

          stderr.writeln(e);

          return _json(503, {'error': 'service_unavailable', 'message': 'Try again later.'});

        }

        return _json(e.statusCode, {

          'error': e.code,

          'message': e.message,

          if (e.retryAfter != null) 'retry_after': e.retryAfter,

          if (e.attemptsRemaining != null) 'attempts_remaining': e.attemptsRemaining,

          if (e.details['fields'] != null) 'fields': e.details['fields'],

        });

      }

    };

// Flutter app side: talks to YOUR backend only. The Udeyou key never ships in the app.

import 'dart:async';

import 'dart:convert';



import 'package:http/http.dart' as http;



class OtpApiException implements Exception {

  OtpApiException(

    this.code,

    this.message, {

    this.retryAfter,

    this.attemptsRemaining,

  });



  final String code;

  final String message;

  final int? retryAfter;

  final int? attemptsRemaining;



  @override

  String toString() => message;

}



class OtpApi {

  OtpApi(this.baseUrl, {http.Client? client}) : _http = client ?? http.Client();



  /// Your backend, for example https://api.example.com

  final String baseUrl;

  final http.Client _http;



  Future<({String otpId, int expiresIn})> sendCode(String email) async {

    final data = await _post('/auth/otp/send', {'email': email});

    return (

      otpId: data['otp_id'] as String,

      expiresIn: data['expires_in'] as int,

    );

  }



  Future<bool> verifyCode(String otpId, String code) async {

    final data = await _post('/auth/otp/verify', {

      'otp_id': otpId,

      'code': code,

    });

    return data['verified'] == true;

  }



  Future<Map<String, dynamic>> _post(

    String path,

    Map<String, String> body,

  ) async {

    final http.Response res;

    try {

      res = await _http

          .post(

            Uri.parse('$baseUrl$path'),

            headers: {'Content-Type': 'application/json'},

            body: jsonEncode(body),

          )

          .timeout(const Duration(seconds: 20));

    } on TimeoutException {

      throw OtpApiException('timeout', 'The server took too long to respond.');

    }



    final Object? json;

    try {

      json = jsonDecode(res.body);

    } on FormatException {

      throw OtpApiException(

        'bad_response',

        'Unexpected server response (${res.statusCode}).',

      );

    }

    final data = json is Map<String, dynamic> ? json : <String, dynamic>{};



    if (res.statusCode != 200) {

      throw OtpApiException(

        data['error'] as String? ?? 'http_${res.statusCode}',

        data['message'] as String? ?? 'Request failed (${res.statusCode}).',

        retryAfter: data['retry_after'] as int?,

        attemptsRemaining: data['attempts_remaining'] as int?,

      );

    }

    return data;

  }

}

import 'package:flutter/material.dart';



import 'otp_api.dart';



class OtpScreen extends StatefulWidget {

  const OtpScreen({super.key, required this.api, required this.onVerified});



  final OtpApi api;

  final ValueChanged<String> onVerified; // receives the verified email



  @override

  State<OtpScreen> createState() => _OtpScreenState();

}



class _OtpScreenState extends State<OtpScreen> {

  final _email = TextEditingController();

  final _code = TextEditingController();

  String? _otpId;

  bool _loading = false;

  String? _error;



  @override

  void dispose() {

    _email.dispose();

    _code.dispose();

    super.dispose();

  }



  Future<void> _run(Future<void> Function() action) async {

    setState(() {

      _loading = true;

      _error = null;

    });

    try {

      await action();

    } on OtpApiException catch (e) {

      _error = switch (e.code) {

        'invalid_code' =>

          'Incorrect code. ${e.attemptsRemaining ?? 0} attempts left.',

        'resend_too_soon' || 'recipient_limit' || 'rate_limited' =>

          'Please wait ${e.retryAfter ?? 60} seconds and try again.',

        'otp_expired' || 'too_many_attempts' =>

          'This code is no longer valid. Request a new one.',

        _ => e.message,

      };

    } catch (_) {

      _error = 'Could not reach the server. Check your connection.';

    } finally {

      if (mounted) setState(() => _loading = false);

    }

  }



  Future<void> _send() => _run(() async {

    final sent = await widget.api.sendCode(_email.text.trim());

    _code.clear();

    _otpId = sent.otpId;

  });



  Future<void> _verify() => _run(() async {

    if (await widget.api.verifyCode(_otpId!, _code.text.trim())) {

      widget.onVerified(_email.text.trim());

    }

  });



  @override

  Widget build(BuildContext context) {

    final codeSent = _otpId != null;

    return Scaffold(

      appBar: AppBar(title: const Text('Sign in')),

      body: ListView(

        padding: const EdgeInsets.all(24),

        children: [

          TextField(

            controller: _email,

            enabled: !_loading,

            keyboardType: TextInputType.emailAddress,

            autofillHints: const [AutofillHints.email],

            decoration: const InputDecoration(labelText: 'Email'),

          ),

          const SizedBox(height: 12),

          OutlinedButton(

            onPressed: _loading ? null : _send,

            child: Text(codeSent ? 'Resend code' : 'Send code'),

          ),

          if (codeSent) ...[

            const SizedBox(height: 24),

            TextField(

              controller: _code,

              enabled: !_loading,

              keyboardType: TextInputType.number,

              autofillHints: const [AutofillHints.oneTimeCode],

              maxLength: 6,

              textAlign: TextAlign.center,

              decoration: const InputDecoration(

                labelText: '6-digit code',

                counterText: '',

              ),

              onSubmitted: (_) => _verify(),

            ),

            const SizedBox(height: 12),

            FilledButton(

              onPressed: _loading ? null : _verify,

              child: const Text('Verify'),

            ),

          ],

          if (_loading)

            const Padding(

              padding: EdgeInsets.only(top: 16),

              child: Center(child: CircularProgressIndicator()),

            ),

          if (_error != null)

            Padding(

              padding: const EdgeInsets.only(top: 16),

              child: Text(

                _error!,

                style: TextStyle(color: Theme.of(context).colorScheme.error),

              ),

            ),

        ],

      ),

    );

  }

}

import 'package:flutter/material.dart';



import 'otp_api.dart';

import 'otp_screen.dart';



void main() => runApp(const App());



class App extends StatelessWidget {

  const App({super.key});



  @override

  Widget build(BuildContext context) {

    return MaterialApp(

      home: Builder(

        builder: (context) => OtpScreen(

          api: OtpApi('https://api.example.com'),

          onVerified: (email) =>

              ScaffoldMessenger.of(context)

                  .showSnackBar(SnackBar(content: Text('Verified $email'))),

        ),

      ),

    );

  }

}